yatfa 1.0.96 → 1.0.98

package/README.md

@@ -79,9 +79,9 @@ Example `yatfa.env.rb`:
 | Variable | Required | Description |
 |----------|----------|-------------|
 | `AGENT_TYPE` | ✅ | `worker`, `planner`, `reviewer`, or `researcher` |
-| `YATFA_URL` | ✅ | YATFA platform URL (WebSocket and API URLs are derived from this) |
-| `YATFA_API_KEY` | | MCP API key (get from YATFA dashboard) |
-| `GH_TOKEN` | | GitHub token for git operations |
+| `YATFA_API_KEY` | ✅ | MCP API key (get from YATFA dashboard) |
+| `YATFA_URL` | | Yatfa platform URL (defaults to `https://yatfa.com`; `YATFA_API_URL` & `YATFA_WS_URL` are derived from this) |
+| `GH_TOKEN` | | GitHub token for git operations (fallback; backend token auth is preferred) |
 
 ## Agent Types
 
@@ -199,7 +199,7 @@ YATFA_API_KEY=your_api_key_here
 AGENT_TYPE=worker
 ```
 
-Note: `YATFA_API_URL` and `YATFA_WS_URL` are derived from `YATFA_URL` by `setup-agent.rb`. Project is automatically determined by the API key authentication.
+Note: `YATFA_URL` is optional and defaults to `https://yatfa.com` (the hosted deployment works with zero URL configuration; self-hosted installs set it to their server). `YATFA_API_URL` (`/api/v1`) and `YATFA_WS_URL` (`/cable`, scheme-adjusted) are always derived from it — you never need to set them. The git credential helper derives `YATFA_API_URL` itself, so even a bare `docker exec` shell with no other env can authenticate. Project is automatically determined by the API key.
 
 ### Agent Self-Update
 

package/lib/yatfa_agent/command_builder.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "json"
+require_relative "../../setup/url_helper"
 
 module YatfaAgent
   # Docker command assembly.
@@ -68,10 +69,12 @@ module YatfaAgent
           docker_cmd += ["-e", "OPENCLAW_TELEGRAM_BOT_TOKEN=#{agent_config['telegram_bot_token']}"]
         end
 
-        # Pass YATFA_URL if configured (optional for claw)
+        # Pass YATFA_URL if configured (optional for claw). The API URL is
+        # derived via the shared UrlHelper so an explicit override is honored
+        # and the /api/v1 suffix rule stays in one place (YATFA-3018).
         if config["yatfa_url"]
           docker_cmd += ["-e", "YATFA_URL=#{config['yatfa_url']}"]
-          docker_cmd += ["-e", "YATFA_API_URL=#{config['yatfa_url']}/api/v1"]
+          docker_cmd += ["-e", "YATFA_API_URL=#{YatfaAgent::UrlHelper.api_url(config)}"]
         end
 
         # Pass MCP API key if configured (for future MCP integration)
@@ -80,14 +83,29 @@ module YatfaAgent
         end
 
       else
-        # Standard agent setup (worker, planner, reviewer, researcher)
+        # Standard agent setup (worker, planner, reviewer, researcher).
+        # Inject all three URLs as container-wide -e env (matching the claw
+        # branch) so any shell in the container — including `docker exec` shells
+        # that are not children of the setup process — sees a consistent
+        # YATFA_API_URL. YATFA_URL defaults to https://yatfa.com; API/WS URLs are
+        # derived from it via the shared UrlHelper (YATFA-3018). Previously only
+        # YATFA_URL + YATFA_API_KEY were injected here, leaving YATFA_API_URL
+        # empty outside the setup process and breaking git auth.
+        #
+        # An operator may override any URL via the env block; those overrides
+        # are already injected above as -e flags, so skip them here to avoid
+        # clobbering (the last -e flag for a key wins in docker). Derivation
+        # uses the effective source so env-block YATFA_URL flows into API/WS.
+        url_source = config.merge(merged_env)
         docker_cmd += [
           "-e", "YATFA_VERSION=main",
           "-e", "SKILLS=#{agent_def[:skills]&.join(',')}",
           "-e", "AGENT_TYPE=#{agent_type}",
-          "-e", "YATFA_URL=#{YatfaAgent::Config.yatfa_url(config)}",
           "-e", "YATFA_API_KEY=#{agent_config['mcp_api_key']}"
         ]
+        docker_cmd += ["-e", "YATFA_URL=#{YatfaAgent::UrlHelper.base_url(url_source)}"]     unless merged_env["YATFA_URL"]
+        docker_cmd += ["-e", "YATFA_API_URL=#{YatfaAgent::UrlHelper.api_url(url_source)}"] unless merged_env["YATFA_API_URL"]
+        docker_cmd += ["-e", "YATFA_WS_URL=#{YatfaAgent::UrlHelper.ws_url(url_source)}"]   unless merged_env["YATFA_WS_URL"]
 
         add_github_auth!(docker_cmd, config)
         add_git_config!(docker_cmd, config)

package/lib/yatfa_agent/config.rb

@@ -3,6 +3,11 @@
 require "json"
 require "digest"
 require_relative "http"
+# Single source of truth for URL→{api,ws} derivation + the hosted default.
+# Loaded here (not duplicated) so the host-side launcher routes ALL URL
+# derivation through YatfaAgent::UrlHelper — the same module the in-container
+# setup scripts use. See YATFA-3018.
+require_relative "../../setup/url_helper"
 
 module YatfaAgent
   module Config
@@ -88,27 +93,6 @@ module YatfaAgent
       JSON.parse(JSON.generate(config))
     end
 
-    def self.yatfa_url(config)
-      config["yatfa_url"] || config["rails_api_url"]
-    end
-
-    def self.api_url(config)
-      # Derive API URL from yatfa_url
-      yatfa_base = yatfa_url(config)
-
-      # If yatfa_url already includes /api/v1, return as-is
-      return yatfa_base if yatfa_base.end_with?("/api/v1") || yatfa_base.end_with?("/api/")
-
-      # Otherwise, assume it's the base URL and append /api/v1
-      "#{yatfa_base}/api/v1"
-    end
-
-    def self.ws_url(config)
-      # Derive WebSocket URL from yatfa_url by replacing protocol and adding /cable endpoint
-      api_base = yatfa_url(config)
-      "#{api_base.sub(/^https:\/\//, "wss://").sub(/^http:\/\//, "ws://")}/cable"
-    end
-
     # Extract the first available agent MCP API key from the config.
     # Returns nil when no key is configured.
     def self.agent_api_key(config)
@@ -123,8 +107,11 @@ module YatfaAgent
     end
 
     def self.fetch_repositories!(config)
-      # Support both old and new config keys
-      api_base = api_url(config)
+      # Derive the API URL through the shared single source of truth
+      # (YatfaAgent::UrlHelper) so this host-side path honors an explicit
+      # YATFA_API_URL override and the hosted default exactly like the
+      # launcher and in-container setup scripts. See YATFA-3018.
+      api_base = YatfaAgent::UrlHelper.api_url(config)
 
       return unless api_base
 

package/lib/yatfa_agent/docker.rb

@@ -49,7 +49,12 @@ module YatfaAgent
     # be identified, the API is unreachable, or no such config is stored.
     # Never raises — a missing remote config is a normal "fall back to error" case.
     def self.fetch_remote_dockerfile(config)
-      api_base = Config.api_url(config)
+      # Derive the API URL through the shared single source of truth
+      # (YatfaAgent::UrlHelper) rather than the legacy Config.api_url, which
+      # neither honored an explicit YATFA_API_URL override nor applied the
+      # hosted default and could raise NoMethodError on an unconfigured URL.
+      # YatfaAgent::UrlHelper is loaded transitively via config.rb. See YATFA-3018.
+      api_base = YatfaAgent::UrlHelper.api_url(config)
       project_id = config["project_id"]
       api_key = Config.agent_api_key(config)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yatfa",
-  "version": "1.0.96",
+  "version": "1.0.98",
   "description": "YATFA - Yet Another Tool For Agents",
   "bin": "./bin/run-yatfa-agent.rb",
   "files": [
@@ -16,4 +16,4 @@
   },
   "author": "",
   "license": "ISC"
-}
+}

package/setup/agent_bridge.rb

@@ -5,7 +5,7 @@
 #
 # Handles:
 #   - Architecture detection and multi-strategy bridge download
-#     (local override → Civo S3 presigned URL → GitHub fallback)
+#     (local override → mounted binary → public bucket download)
 #   - tmux binary download and INSIDE_TMUX=1 patching
 #   - Generic file download utility (download_file)
 #   - Helper script installation to /usr/local/bin
@@ -58,22 +58,12 @@ def download_agent_bridge!
     return download_agent_bridge_tmux!(target_dir)
   end
 
-  # 3. Try Civo bucket download (production mode)
-  if ENV["CIVO_ACCESS_KEY_ID"] && ENV["CIVO_SECRET_KEY"]
-    puts "📥 Downloading agent-bridge from Civo bucket..."
-    if download_from_civo!(arch, target_dir)
-      return download_agent_bridge_tmux!(target_dir)
-    else
-      puts "⚠️  Civo download failed, falling back to GitHub..."
-    end
-  end
-
-  # 4. Fallback to GitHub raw URLs (legacy)
+  # 3. Download from the public bucket (production mode)
   bridge_url = "#{YATFA_RAW_URL}/bin/agent-bridge-linux-#{arch}"
-  puts "📥 Downloading agent-bridge for linux-#{arch} from GitHub..."
+  puts "📥 Downloading agent-bridge for linux-#{arch} from bucket..."
   system("sudo", "curl", "-fsSL", bridge_url, "-o", "#{target_dir}/agent-bridge")
   unless $?.success?
-    puts "❌ Failed to download agent-bridge from GitHub"
+    puts "❌ Failed to download agent-bridge from #{bridge_url}"
     exit 1
   end
   system("sudo", "chmod", "+x", "#{target_dir}/agent-bridge")
@@ -82,63 +72,6 @@ def download_agent_bridge!
   download_agent_bridge_tmux!(target_dir)
 end
 
-def download_from_civo!(arch, target_dir)
-  require "aws-sdk-s3"
-
-  region = ENV["CIVO_REGION"] || "LON1"
-  endpoint = ENV["CIVO_ENDPOINT"] || "https://objectstore.fra1.civo.com"
-  bucket = ENV["YATFA_BINARIES_BUCKET"] || "yatfa"
-  version = ENV["AGENT_BRIDGE_VERSION"] || "latest"
-
-  binary_name = "agent-bridge-linux-#{arch}"
-  key = "agent-bridge/#{version}/#{binary_name}"
-
-  puts "   Region: #{region}"
-  puts "   Bucket: #{bucket}"
-  puts "   Version: #{version}"
-  puts "   Binary: #{binary_name}"
-
-  begin
-    # Configure Civo S3-compatible client
-    Aws.config.update({
-      region: region,
-      endpoint: endpoint,
-      access_key_id: ENV["CIVO_ACCESS_KEY_ID"],
-      secret_access_key: ENV["CIVO_SECRET_KEY"]
-    })
-
-    s3 = Aws::S3::Resource.new
-    obj = s3.bucket(bucket).object(key)
-
-    # Generate presigned URL (valid for 1 hour)
-    url = obj.presigned_url(:get, expires_in: 3600)
-
-    puts "✅ Generated presigned URL"
-
-    # Download via curl (array form avoids shell interpolation of URL)
-    system("sudo", "curl", "-fsSL", url, "-o", "#{target_dir}/agent-bridge")
-
-    unless $?.success?
-      puts "❌ Failed to download agent-bridge from Civo"
-      return false
-    end
-
-    system("sudo", "chmod", "+x", "#{target_dir}/agent-bridge")
-    puts "✅ Downloaded agent-bridge from Civo"
-    return true
-
-  rescue LoadError
-    puts "⚠️  aws-sdk-s3 gem not installed"
-    return false
-  rescue Aws::S3::Errors::NoSuchKey
-    puts "❌ Version #{version} not found in bucket"
-    return false
-  rescue => e
-    puts "❌ Civo download failed: #{e.message}"
-    return false
-  end
-end
-
 def download_agent_bridge_tmux!(target_dir)
   bridge_tmux_url = "#{YATFA_RAW_URL}/bin/agent-bridge-tmux"
 

package/setup/git_credential_helper.rb

@@ -36,6 +36,41 @@ require "uri"
 require "time"
 require "fileutils"
 
+# Self-healing URL derivation (YATFA-3018). This helper runs in isolation as
+# /usr/local/bin/git-auth-helper (copied there by setup-github.rb alongside
+# url_helper.rb), so it derives YATFA_API_URL from YATFA_URL itself — defaulting
+# to https://yatfa.com — rather than bailing when YATFA_API_URL is empty (the
+# exact failure operators hit in `docker exec` shells outside the setup
+# process). Load the shared module: in-tree via require_relative (tests / setup/),
+# or from the absolute install path when running as the copied binary. A
+# last-resort inline mirror keeps auth working even if the sibling file is
+# missing (version skew / half install) — a credential helper must never break
+# on a missing file. Keep the mirror in sync with setup/url_helper.rb.
+begin
+  require_relative "url_helper"
+rescue LoadError
+  begin
+    require "/usr/local/bin/url_helper"
+  rescue LoadError
+    module YatfaAgent
+      module UrlHelper
+        DEFAULT_YATFA_URL = "https://yatfa.com"
+
+        module_function
+
+        def api_url(source = ENV)
+          explicit = source["YATFA_API_URL"].to_s.strip
+          return explicit unless explicit.empty?
+
+          base = source["YATFA_URL"].to_s.strip
+          base = DEFAULT_YATFA_URL if base.empty?
+          base.end_with?("/api/v1") || base.end_with?("/api/") ? base : "#{base}/api/v1"
+        end
+      end
+    end
+  end
+end
+
 module YatfaAgent
   module GitCredentialHelper
     DEFAULT_CACHE_DIR = "/tmp/github-token-cache"
@@ -116,9 +151,11 @@ module YatfaAgent
     # using the per-installation cache and falling back to the default token
     # when a repo-scoped fetch fails (older backend, unregistered repo, etc.).
     def resolve_token(repo, cache_dir:, env:, http_fetch:)
-      api_url = env["YATFA_API_URL"]
+      # Self-heal: derive YATFA_API_URL from YATFA_URL (default https://yatfa.com)
+      # when not explicitly set, so a bare `docker exec` shell with no manual
+      # export can still auth. An explicit YATFA_API_URL override is honored.
+      api_url = YatfaAgent::UrlHelper.api_url(env)
       api_key = env["YATFA_API_KEY"]
-      return nil if api_url.nil? || api_url.to_s.empty?
       return nil if api_key.nil? || api_key.to_s.empty?
 
       cached = read_cached_token(repo, cache_dir)
@@ -134,6 +171,19 @@ module YatfaAgent
       data["token"]
     end
 
+    # When required config is missing, return a specific diagnostic naming the
+    # offending variable; otherwise nil. The API URL is self-healed (derived
+    # from YATFA_URL, default https://yatfa.com), so the only hard requirement
+    # is the YATFA_API_KEY secret — previously this surfaced as the opaque
+    # "failed to obtain GitHub token" (YATFA-3018).
+    def missing_config_message(env_hash, repo: nil)
+      api_key = env_hash["YATFA_API_KEY"]
+      return nil unless api_key.nil? || api_key.to_s.empty?
+
+      repo_suffix = repo ? " for #{repo}" : ""
+      "git-auth-helper: YATFA_API_KEY is not set — cannot mint a GitHub token#{repo_suffix}"
+    end
+
     # Dispatch entry point. Returns a process exit code (0 success, 1 failure).
     def run(argv, stdin: $stdin, stdout: $stdout, stderr: $stderr,
             cache_dir: DEFAULT_CACHE_DIR, env: nil, http_fetch: nil)
@@ -145,6 +195,10 @@ module YatfaAgent
         if action == "get"
           attrs = parse_input(read_stdin(stdin))
           repo = normalize_path(attrs["path"])
+          if (msg = missing_config_message(env_hash, repo: repo))
+            stderr.puts(msg)
+            return 1
+          end
           token = resolve_token(repo, cache_dir: cache_dir, env: env_hash, http_fetch: fetch)
           if token.nil?
             stderr.puts("git-auth-helper: failed to obtain GitHub token" + (repo ? " for #{repo}" : ""))
@@ -160,6 +214,10 @@ module YatfaAgent
       end
 
       # Token-only mode (e.g. the `gh` wrapper): print just the default token.
+      if (msg = missing_config_message(env_hash))
+        stderr.puts(msg)
+        return 1
+      end
       token = resolve_token(nil, cache_dir: cache_dir, env: env_hash, http_fetch: fetch)
       if token.nil?
         stderr.puts("git-auth-helper: failed to obtain GitHub token")

package/setup/setup-agent.rb

@@ -36,6 +36,7 @@ require "time"
 require "socket"
 require "timeout"
 require_relative "http_client"
+require_relative "url_helper"
 require_relative "setup-github"
 require_relative "repositories"
 require_relative "agent_bridge"
@@ -52,47 +53,32 @@ YATFA_RAW_URL = "#{YATFA_SCRIPTS_BASE_URL}/#{YATFA_VERSION}"
 VALID_AGENT_TYPES = %w[planner worker reviewer researcher claw]
 
 def check_env!
-  agent_type = ENV["AGENT_TYPE"]
-
   # Note: claw agents have a separate entry point in setup-claw-agent.rb
   # which calls check_env_claw! directly. This method only handles standard agent types.
 
-  required = %w[YATFA_URL]
-  missing = required.select { |var| ENV[var].to_s.empty? }
-  unless missing.empty?
-    puts "❌ Missing environment variables: #{missing.join(', ')}"
-    puts ""
-    puts "Required:"
-    puts "  YATFA_URL   - Yatfa platform URL (https://yatfa.example.com)"
+  # YATFA_API_KEY is the single required secret — the agent cannot authenticate
+  # to the backend or mint GitHub tokens without it. Fail fast with a specific
+  # message rather than starting a half-working agent (YATFA-3018).
+  if ENV["YATFA_API_KEY"].to_s.empty?
+    puts "❌ Missing required environment variable: YATFA_API_KEY"
+    puts "   YATFA_API_KEY is the MCP API key for this agent (from the Yatfa dashboard)."
+    puts "   The agent needs it to authenticate to the backend and to mint GitHub tokens."
     puts ""
-    puts "Optional:"
-    puts "  YATFA_API_URL  - API URL for MCP tools (derived from YATFA_URL)"
-    puts "  YATFA_API_KEY  - MCP API key"
-    puts "  GH_TOKEN       - GitHub token"
+    puts "YATFA_URL is optional (defaults to https://yatfa.com);"
+    puts "  YATFA_API_URL / YATFA_WS_URL are derived from it."
     exit 1
   end
 
-  # Derive YATFA_API_URL and YATFA_WS_URL from YATFA_URL if not set
-  # IMPORTANT: Always use original YATFA_URL for derivations, not modified values
-  yatfa_url = ENV["YATFA_URL"]
-
-  # Derive YATFA_API_URL: append /api/v1 if not already present
-  unless ENV["YATFA_API_URL"]
-    if yatfa_url.end_with?("/api/v1") || yatfa_url.end_with?("/api/")
-      ENV["YATFA_API_URL"] = yatfa_url
-    else
-      ENV["YATFA_API_URL"] = "#{yatfa_url}/api/v1"
-    end
-    puts "📡 Derived YATFA_API_URL: #{ENV['YATFA_API_URL']}"
-  end
-
-  # Derive YATFA_WS_URL: replace protocol with ws/wss and add /cable endpoint
-  # IMPORTANT: Use original yatfa_url before any modifications
-  original_yatfa_url = ENV["YATFA_URL"]
-  unless ENV["YATFA_WS_URL"]
-    ENV["YATFA_WS_URL"] = "#{original_yatfa_url.sub(/^https:\/\//, 'wss://').sub(/^http:\/\//, 'ws://')}/cable"
-    puts "📡 Derived YATFA_WS_URL: #{ENV['YATFA_WS_URL']}"
-  end
+  # Derive the three URLs via the shared UrlHelper (YATFA-3018). YATFA_URL
+  # defaults to https://yatfa.com when unset; YATFA_API_URL (/api/v1) and
+  # YATFA_WS_URL (scheme-swapped /cable) are derived from it. Explicit
+  # overrides for any of the three are honored (backwards compatible).
+  ENV["YATFA_URL"]     = YatfaAgent::UrlHelper.base_url
+  ENV["YATFA_API_URL"] = YatfaAgent::UrlHelper.api_url
+  ENV["YATFA_WS_URL"]  = YatfaAgent::UrlHelper.ws_url
+  puts "📡 YATFA_URL:     #{ENV['YATFA_URL']}"
+  puts "📡 YATFA_API_URL: #{ENV['YATFA_API_URL']}"
+  puts "📡 YATFA_WS_URL:  #{ENV['YATFA_WS_URL']}"
 
   agent_type = ENV["AGENT_TYPE"]
   if agent_type && !VALID_AGENT_TYPES.include?(agent_type)

package/setup/setup-claw-agent.rb

@@ -14,6 +14,9 @@
 #   - fetch_llm_credentials! is defined by the parent setup-agent.rb
 #   - Standard library requires (json, fileutils, pathname, etc.) are loaded
 #     by setup-agent.rb before this file is required
+#   - YatfaAgent::UrlHelper is provided by setup/url_helper.rb
+
+require_relative "url_helper" unless defined?(YatfaAgent::UrlHelper)
 
 def check_env_claw!
   required = %w[OPENCLAW_TELEGRAM_BOT_TOKEN]
@@ -37,9 +40,11 @@ def check_env_claw!
     exit 1
   end
 
-  # Derive YATFA_API_URL from YATFA_URL if set (optional for claw)
+  # Derive YATFA_API_URL from YATFA_URL via the shared helper (optional for
+  # claw — yatfa integration is opt-in, so only when YATFA_URL is set). The
+  # /api/v1 suffix rule lives in one place (YATFA-3018).
   if ENV["YATFA_URL"] && !ENV["YATFA_API_URL"]
-    ENV["YATFA_API_URL"] = "#{ENV['YATFA_URL']}/api/v1"
+    ENV["YATFA_API_URL"] = YatfaAgent::UrlHelper.with_api_suffix(ENV["YATFA_URL"])
   end
 
   puts "✅ Claw environment validated"

package/setup/setup-github.rb

@@ -4,26 +4,14 @@
 # Extracted from setup-agent.rb for modularity
 
 def setup_github_auth!
-  rails_api_url = ENV["YATFA_API_URL"]
   rails_api_key = ENV["YATFA_API_KEY"]
 
-  # Derive YATFA_API_URL from YATFA_URL if not set
-  unless rails_api_url && !rails_api_url.empty?
-    yatfa_url = ENV["YATFA_URL"]
-    if yatfa_url && !yatfa_url.empty?
-      rails_api_url = "#{yatfa_url}/api/v1"
-      ENV["YATFA_API_URL"] = rails_api_url
-    end
-  end
-
-  # Validate YATFA_API_URL format before proceeding
-  if rails_api_url && !rails_api_url.empty? && !rails_api_url.include?('/api/v1')
-    puts "⚠️  Warning: YATFA_API_URL must include /api/v1 path"
-    puts "   Current: #{rails_api_url}"
-    puts "   Expected: https://example.com/api/v1"
-    puts "   Falling back to alternative authentication..."
-    rails_api_url = nil  # Clear it to fall through to other methods
-  end
+  # Derive YATFA_API_URL via the shared UrlHelper (YATFA-3018): honors an
+  # explicit override, else derives /api/v1 from YATFA_URL (default
+  # https://yatfa.com). check_env! already set this for standard agents, but
+  # re-derive defensively so a re-run / partial flow is consistent.
+  ENV["YATFA_API_URL"] = YatfaAgent::UrlHelper.api_url
+  rails_api_url = ENV["YATFA_API_URL"]
 
   # New method: Get token from Rails backend (preferred)
   if rails_api_url && !rails_api_url.empty? && rails_api_key && !rails_api_key.empty?
@@ -38,6 +26,16 @@ def setup_github_auth!
     system("sudo", "mv", "/tmp/git-auth-helper", helper_path)
     system("sudo", "chmod", "+x", helper_path)
 
+    # Install the shared URL helper alongside the credential helper. The helper
+    # runs in isolation as /usr/local/bin/git-auth-helper and loads it via
+    # `require_relative "url_helper"` to self-heal YATFA_API_URL from YATFA_URL
+    # (default https://yatfa.com) in bare `docker exec` shells (YATFA-3018).
+    url_helper_src = File.join(__dir__, "url_helper.rb")
+    if File.exist?(url_helper_src)
+      File.write("/tmp/url_helper", File.read(url_helper_src))
+      system("sudo", "mv", "/tmp/url_helper", "/usr/local/bin/url_helper.rb")
+    end
+
     # Wire the helper into git. useHttpPath=true makes git send the repo path on
     # stdin so the helper can request a repo-scoped token (?repo=owner/repo).
     # Array form avoids shell interpolation of the helper path.

package/setup/skills.rb

@@ -4,7 +4,7 @@
 # Extracted from setup-agent.rb for modularity (Round 2)
 #
 # Handles:
-#   - Installing built-in skills from the SKILLS env var (Civo-hosted SKILL.md files)
+#   - Installing built-in skills from the SKILLS env var (R2-hosted SKILL.md files)
 #   - Fetching community skills list from the backend whoami API
 #   - Installing community skills from external GitHub repos
 #

package/setup/url_helper.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+# YATFA URL derivation — the single source of truth.
+#
+# `YATFA_URL` is the only URL variable an operator ever configures. The API URL
+# (`<base>/api/v1`) and the WebSocket URL (`<scheme-adjusted base>/cable`) are
+# ALWAYS derived from it. Both the host-side launcher (lib/yatfa_agent/) and the
+# in-container setup scripts (setup/*) load this module so the derivation lives
+# in exactly one place.
+#
+# Rules (see YATFA-3018):
+#   1. `YATFA_URL` defaults to `https://yatfa.com` when unset/blank, so the
+#      hosted deployment works with zero URL configuration.
+#   2. `YATFA_API_URL` / `YATFA_WS_URL`, when explicitly set, are honored as
+#      overrides (backwards compatible) — never re-derived.
+#   3. The API URL appends `/api/v1` unless the base already carries an `/api`
+#      path; the WS URL swaps the scheme (http→ws, https→wss) and appends
+#      `/cable`.
+#
+# Every method takes an optional +source+ — any hash-like object (ENV, or a
+# string-keyed config hash) — so the same logic serves the launcher (config
+# hash) and the container scripts (ENV).
+
+module YatfaAgent
+  module UrlHelper
+    DEFAULT_YATFA_URL = "https://yatfa.com"
+    API_SUFFIX = "/api/v1"
+    WS_SUFFIX = "/cable"
+
+    module_function
+
+    # Resolve the base platform URL, applying the hosted default when unset.
+    # Reads +YATFA_URL+ (ENV convention) then +yatfa_url+ / +rails_api_url+
+    # (config-hash convention).
+    def base_url(source = ENV)
+      value = source_value(source, "YATFA_URL") ||
+              source_value(source, "yatfa_url") ||
+              source_value(source, "rails_api_url")
+      value = value.to_s.strip
+      value.empty? ? DEFAULT_YATFA_URL : value
+    end
+
+    # Derive the API URL. An explicit +YATFA_API_URL+ override wins; otherwise
+    # the suffix is appended to the resolved base URL.
+    def api_url(source = ENV)
+      explicit = source_value(source, "YATFA_API_URL").to_s.strip
+      return explicit unless explicit.empty?
+
+      with_api_suffix(base_url(source))
+    end
+
+    # Derive the WebSocket URL. An explicit +YATFA_WS_URL+ override wins;
+    # otherwise the base scheme is swapped (http→ws, https→wss) and +/cable+
+    # is appended.
+    def ws_url(source = ENV)
+      explicit = source_value(source, "YATFA_WS_URL").to_s.strip
+      return explicit unless explicit.empty?
+
+      "#{to_ws_scheme(base_url(source))}#{WS_SUFFIX}"
+    end
+
+    # Append +/api/v1+ to +base+ unless it already ends with +/api/v1+ or
+    # +/api/+. Shared with YatfaAgent::Config so the suffix rule is defined once.
+    def with_api_suffix(base)
+      base = base.to_s
+      return base if base.end_with?("/api/v1") || base.end_with?("/api/")
+
+      "#{base}#{API_SUFFIX}"
+    end
+
+    # Swap the scheme of +base+ to its WebSocket equivalent. Already-ws schemes
+    # are left untouched.
+    def to_ws_scheme(base)
+      base.to_s.sub(/\Ahttps:\/\//, "wss://").sub(/\Ahttp:\/\//, "ws://")
+    end
+
+    # Safely read +key+ from a hash-like +source+ (ENV or a config Hash).
+    def source_value(source, key)
+      return nil unless source.respond_to?(:[])
+
+      source[key]
+    rescue StandardError
+      nil
+    end
+  end
+end