[issue-2769][slice-1/2] Gateway upstream router + LiteLLM Deploymen...

Makefile

@@ -504,10 +504,20 @@ k3s-secrets:  ## Create gateway secrets from ~/.config/egg/
 	fi
 	@echo "==> Creating gateway-secrets in egg-system namespace..."
 	@echo "   (all files under ~/.config/egg/ become keys in the secret)"
+	@# LiteLLM master key (issue #2769): the in-cluster LiteLLM
+	@# Deployment expects ``gateway-secrets.litellm-master-key`` so the
+	@# gateway's injected x-api-key matches LiteLLM's master_key. The
+	@# value lives in ``secrets.env`` as ``LITELLM_MASTER_KEY=...``;
+	@# extract it and surface it as a discrete literal key so both
+	@# sides of the wire share one source of truth. Empty value is the
+	@# no-op default (the manifest reads the Secret with
+	@# ``optional: true``).
+	@LITELLM_KEY="$$(grep -E '^[[:space:]]*LITELLM_MASTER_KEY[[:space:]]*=' "$$HOME/.config/egg/secrets.env" 2>/dev/null | tail -n1 | cut -d= -f2- | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$$//' -e 's/^"//' -e 's/"$$//' -e "s/^'//" -e "s/'$$//")"; \
 	export KUBECONFIG=$${KUBECONFIG:-/etc/rancher/k3s/k3s.yaml} && \
 	kubectl apply -f k8s/base/namespaces.yaml && \
 	kubectl -n egg-system create secret generic gateway-secrets \
 		--from-file=$$HOME/.config/egg/ \
+		--from-literal=litellm-master-key="$$LITELLM_KEY" \
 		--dry-run=client -o yaml | kubectl apply -f -
 
 deploy: k3s-secrets  ## Deploy egg to k3s

config/repo_config.py

@@ -307,6 +307,56 @@ def should_disable_auto_fix(repo: str) -> bool:
     return cast(bool, get_repo_setting(repo, "disable_auto_fix", False))
 
 
+def get_default_agent_model(repo: str) -> str | None:
+    """Return the repository-level default agent model, or ``None`` when unset.
+
+    This is the second tier of the per-agent model resolution precedence
+    (see ``orchestrator/agent_model_resolution.py``):
+
+    1. ``PipelineConfig.agent_models[role]`` (per-pipeline override)
+    2. ``repositories.yaml`` ``default_agent_model`` (this helper)
+    3. Built-in ``"opus"`` default
+
+    The value follows the same classifier as ``agent_models``: a recognised
+    Claude alias (``opus``, ``opus[1m]``, ``sonnet``, ``sonnet[1m]``,
+    ``haiku``, ``claude-*``) routes through the Anthropic upstream, anything
+    else routes through the in-cluster LiteLLM proxy with the alias
+    ``"opus"`` presented to Claude Code (cq-5 mitigation).
+
+    Args:
+        repo: Repository in "owner/repo" format
+
+    Returns:
+        The configured model string, or ``None`` when the repo has no
+        per-repo entry, the entry omits ``default_agent_model``, or the
+        ``repositories.yaml`` file is absent (a missing config file is the
+        same observable as a missing entry — preserves the
+        no-op-by-default invariant for callers like ``resolve_agent_model``
+        that run inside spawn paths where the config file may not be
+        present, e.g. unit tests and ephemeral CI environments).
+
+    Raises:
+        ValueError: When ``default_agent_model`` is set to a non-string
+            YAML value (e.g. ``default_agent_model: 4``). Surfacing the
+            misconfiguration loudly here keeps it out of ``classify_model``,
+            where a non-string would otherwise raise an opaque ``TypeError``
+            from the regex internals.
+    """
+    try:
+        value = get_repo_setting(repo, "default_agent_model", None)
+    except FileNotFoundError:
+        return None
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        raise ValueError(
+            f"default_agent_model for {repo!r} must be a string, got "
+            f"{type(value).__name__}: {value!r}. Set it to a recognised "
+            f"Claude alias (opus, sonnet, …) or a LiteLLM model name."
+        )
+    return value
+
+
 try:
     from egg_config.validators import validate_checks
 except ImportError:

config/repositories.yaml.example

@@ -109,6 +109,17 @@ readable_repos:
 #     **/*_test.go in tests_globs). Security-relevant blocklists
 #     (.egg-state/contracts/, .github/) are hard-coded and cannot be
 #     relaxed. See docs/guides/sdlc-pipeline.md#per-repository-role-patterns.
+#   - default_agent_model: Repository-level default for the per-agent
+#     model knob added in #2769. Used by every agent role unless the
+#     pipeline submission overrides it via ``agent_models``. A recognised
+#     Claude alias (opus, opus[1m], sonnet, sonnet[1m], haiku, claude-*)
+#     routes through the Anthropic upstream; anything else routes through the
+#     in-cluster LiteLLM proxy with the recognised alias "opus" presented
+#     to Claude Code (cq-5 mitigation). Precedence:
+#       PipelineConfig.agent_models[role]
+#         > this default_agent_model
+#           > built-in "opus" default
+#     Default: not set (every role runs on built-in "opus").
 repo_settings:
   # Example:
   # YOUR_USERNAME/egg:
@@ -190,6 +201,13 @@ repo_settings:
   #     tests_globs: ["**/__tests__/**", "**/*.test.ts", "**/*.test.tsx", "**/*.spec.ts"]
   #     code_globs:  ["**/*.ts", "**/*.tsx", "**/*.js"]
   #     docs_globs:  ["**/*.md", "docs/"]
+  #
+  # # Per-agent model example (#2769): route every role on this repo through
+  # # the LiteLLM proxy by default, picking up the hosted-Qwen model entry
+  # # populated in the LiteLLM ConfigMap. The pipeline-level ``agent_models``
+  # # field still wins when set.
+  # YOUR_USERNAME/qwen-pilot:
+  #   default_agent_model: qwen3-coder-30b
 
 # User mode configuration (optional)
 # When auth_mode is set to "user" for a repo, operations will be

config/secrets.template.env

@@ -24,6 +24,24 @@
 ANTHROPIC_API_KEY=""
 ANTHROPIC_OAUTH_TOKEN=""
 
+# =============================================================================
+# LiteLLM Proxy (Optional — non-Claude model routing, issue #2769)
+# =============================================================================
+# Master key the gateway injects as ``x-api-key`` on every request routed
+# through the in-cluster LiteLLM proxy. The same value is consumed by the
+# LiteLLM Deployment via the ``gateway-secrets`` Secret (key
+# ``litellm-master-key``) so both sides of the wire agree.
+#
+# Per-backend provider credentials (e.g. TOGETHER_API_KEY for a hosted
+# Qwen provider — see cq-6) are NOT stored here; they go in LiteLLM's
+# own env-var slots so the gateway never sees the raw provider key.
+#
+# Leave empty to disable LiteLLM routing — no agent will be routed to
+# LiteLLM with this unset, regardless of any per-pipeline
+# ``agent_models`` override. The Claude path is byte-identical.
+
+LITELLM_MASTER_KEY=""
+
 # =============================================================================
 # Slack Integration
 # =============================================================================

docs/architecture/README.md

@@ -187,6 +187,7 @@ The SDLC pipeline orchestrates agent-based development with structurally enforce
 - [Gateway Auto-Filter](gateway-auto-filter.md) - Restricted-path rejection on push and the commit-authorship registry that backs attribution
 - [Credential Injection](credential-injection.md) - Zero-credential sandbox with API key proxy
 - [Network Isolation](network-isolation.md) - Public/private network modes
+- [Upstream Routing](upstream-routing.md) - `UpstreamRegistry` seam, LiteLLM topology, per-session routing decision, and no-op-by-default invariant for non-Claude agent backends ([#2769](https://github.com/jwbron/egg/issues/2769))
 - [SDLC Pipeline](sdlc-pipeline.md) - Structurally enforced agent checkpoints
 - [Declarative Setup](declarative-setup.md) - Python-based setup
 - [Logging](logging.md) - Structured JSON logging

docs/architecture/orchestrator.md

@@ -244,6 +244,25 @@ See `plugins/refine-plan/skills/refine-plan/agents/applier.md`'s "Out of scope:
 - Orchestrator-side drain hook: `orchestrator/routes/pipelines.py::_drain_wontdo_batch_after_apply` — invoked from both the auto-advance and HITL-resolution apply-phase exit paths; writes per-Task `jira_action_status` back via the `on_entry_result` callback.
 - Issue-level decision record: [#1557 decision-15](https://github.com/jwbron/egg/issues/1557) (trust-boundary for Jira transitions).
 
+## Upstream Routing (Per-Agent Model Backends, [#2769](https://github.com/jwbron/egg/issues/2769))
+
+Per-agent `/v1/messages` traffic routes through an `UpstreamRegistry`
+in the gateway that resolves the upstream (Anthropic vs LiteLLM) from
+per-session metadata declared by the orchestrator at session-create
+time — the same IP-keyed session lookup that already drives
+`session_mode`. Slice 1 of #2769 lands the router and the LiteLLM
+Deployment + Service in `egg-system`, no-op by default; slice 2 adds
+`PipelineConfig.agent_models` and a repository-level
+`default_agent_model` for the orchestrator-side resolution. Until an
+operator opts in, every existing pipeline keeps running on Claude
+with byte-identical gateway behavior.
+
+See [Upstream Routing](upstream-routing.md) for the gateway-side
+seam (registry, credential layout, request lifecycle, failure
+policy, and the no-op-by-default invariant). The operator-facing
+setup ships in slice 2 as `docs/guides/per-agent-models.md` (that
+file does not exist until slice 2 lands).
+
 ## Network Mode
 
 Pipelines can specify an explicit network mode that controls internet access for spawned containers: