feat: v0.1.3 — fallback model array + OPENROUTER_USAGE_HIDDEN_KEYS (#22)

* feat(llm): plumb fallback_model as Vec<String> with FallbackSpec untagged enum

* feat(llm): walk full fallback_model chain on retry, filter empty candidates

* feat(server): add OPENROUTER_USAGE_HIDDEN_KEYS env-driven usage filter config

* feat(api): strip configured usage keys from sync /message response

* chore(examples): switch chat_companion to fallback array form

The "fallback will be a list in a future iteration" TODO from PR #20
is no longer accurate — v0.1.3 implements the array. Switch the
chat_companion task to the new array form to exercise the new code
path in the example, leave the other tasks on the single-string form
so the legacy compat path stays covered. Update the surrounding
comment to describe the dual-shape contract + explicit-empty opt-out.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs: document OPENROUTER_USAGE_HIDDEN_KEYS env

EN + ZH README Configuration tables gain a row for the new
deployer-set env var; .env.example gains a commented example
explaining why a deployer might want to hide cost from a
downstream-facing response without losing operator tracing.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(llm-audit): document OPENROUTER_USAGE_HIDDEN_KEYS

Add a "Hiding fields from the response" section under the Outbound
usage echo block (EN + ZH). Explains the env var semantics, scope
(sync /message only), tracing-unaffected guarantee, the top-level-only
behaviour (list a parent key to suppress its entire subtree), and the
pass-through default.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore(release): bump workspace to 0.1.3 + regen OpenAPI snapshot

Ships the fallback-model array support (TaskConfig.fallback can be a
single string or an ordered array; OpenRouterClient::execute walks the
chain sequentially) plus the OPENROUTER_USAGE_HIDDEN_KEYS deployer-set
env var that strips named keys from the sync /message response's usage
echo while leaving tracing intact. crates.io republish + GHCR build +
fly deploy follow this commit's merge.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore(examples): extend fallback array to insight + memory extraction

User-driven follow-up to T5: insight_extraction now fans out to
two fallback models (anthropic/claude-haiku-4.5 then
deepseek/deepseek-v4-flash) instead of one. memory_extraction
primary swapped to x-ai/grok-4.1-fast with the same two-entry
fallback chain. Exercises the new chain-walker on more code
paths in production traffic.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: enriquephl

.env.example

@@ -14,6 +14,13 @@ OPENROUTER_API_KEY=sk-or-...
 # OPENROUTER_APP_REFERER=https://eros.example
 # OPENROUTER_APP_TITLE=Eros
 
+# OpenRouter response-side usage filter (optional). Comma-separated list
+# of top-level keys to strip from the sync /message response's `usage`
+# object before it leaves the engine. Tracing is unaffected. Hide your
+# wholesale cost from downstream customers without losing operator
+# observability.
+# OPENROUTER_USAGE_HIDDEN_KEYS=cost,cost_details
+
 # Supabase project — same as eros-gateway.
 # Setting SUPABASE_URL is enough on modern projects: the engine derives the
 # JWKS URL (${SUPABASE_URL}/auth/v1/.well-known/jwks.json) and validates

Cargo.lock

@@ -3,7 +3,7 @@ resolver = "2"
 members = ["crates/*"]
 
 [workspace.package]
-version = "0.1.2"
+version = "0.1.3"
 edition = "2021"
 license = "AGPL-3.0-only"
 repository = "https://github.com/etherfunlab/eros-engine"

Cargo.toml

@@ -214,6 +214,7 @@ The `AuthValidator` trait is pluggable if you use a different identity provider.
 | `OPENROUTER_API_KEY` | yes | Chat completions, routed by `examples/model_config.toml` unless overridden. |
 | `OPENROUTER_APP_REFERER` | no | When set, sent as `HTTP-Referer` on every outbound OpenRouter call. Shows up on OpenRouter's app analytics dashboard. |
 | `OPENROUTER_APP_TITLE` | no | When set, sent as `X-Title`. Display name in OpenRouter app analytics. Pairs with `OPENROUTER_APP_REFERER`; both optional. |
+| `OPENROUTER_USAGE_HIDDEN_KEYS` | no | Comma-separated list of top-level keys to strip from the sync `/message` response's `usage` object. Useful for hiding wholesale `cost` / `cost_details` from downstream customers. Server-side tracing is unaffected. |
 | `VOYAGE_API_KEY` | yes | Embeddings. Empty keys fail server boot. |
 | `SUPABASE_URL` | no | Supabase project URL. Kept in `.env.example` for client/deploy conventions; the server does not read it today. |
 | `SUPABASE_JWT_SECRET` | yes | JWT signing secret for default auth. |

README.md

@@ -174,6 +174,7 @@ Server 默認監聽 `0.0.0.0:8080`。Scalar API docs 在 `/docs`，OpenAPI JSON
 | `OPENROUTER_API_KEY` | 是 | Chat completions；默認由 `examples/model_config.toml` 路由。 |
 | `OPENROUTER_APP_REFERER` | 否 | 設了之後每次出站 OpenRouter 調用都帶 `HTTP-Referer`。會出現在 OpenRouter 的 app 分析面板上。 |
 | `OPENROUTER_APP_TITLE` | 否 | 設了之後帶 `X-Title`。OpenRouter app analytics 顯示名稱。和 `OPENROUTER_APP_REFERER` 一對；兩個都可選。 |
+| `OPENROUTER_USAGE_HIDDEN_KEYS` | 否 | 逗号分隔的顶层 key 列表，从 sync `/message` 响应的 `usage` 对象里剔除。常用于把批发 `cost` / `cost_details` 隐藏起来不外泄给下游客户。服务器端 tracing 不受影响。 |
 | `VOYAGE_API_KEY` | 是 | Embeddings。空 key 會拒絕啟動。 |
 | `SUPABASE_URL` | 否 | Supabase project URL。保留在 `.env.example` 裡方便 client / deploy 約定；目前 server 不讀取它。 |
 | `SUPABASE_JWT_SECRET` | 是 | 默認 auth 使用的 JWT signing secret。 |

README.zh.md

@@ -12,7 +12,7 @@ keywords = ["companion", "openrouter", "voyage", "embeddings", "llm"]
 categories = ["api-bindings"]
 
 [dependencies]
-eros-engine-core = { path = "../eros-engine-core", version = "0.1.2" }
+eros-engine-core = { path = "../eros-engine-core", version = "0.1.3" }
 serde = { workspace = true }
 serde_json = { workspace = true }
 reqwest = { workspace = true }

crates/eros-engine-llm/Cargo.toml

@@ -11,6 +11,26 @@ const FALLBACK_MODEL: &str = "x-ai/grok-4-mini";
 const FALLBACK_TEMPERATURE: f64 = 0.5;
 const FALLBACK_MAX_TOKENS: u32 = 200;
 
+/// Per-task fallback shape — accepts either a single model id (legacy)
+/// or an ordered array. Normalised to `Vec<String>` via `into_vec()`
+/// in the resolver; empty entries are filtered out.
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
+#[serde(untagged)]
+pub enum FallbackSpec {
+    Single(String),
+    Multiple(Vec<String>),
+}
+
+impl FallbackSpec {
+    pub fn into_vec(self) -> Vec<String> {
+        match self {
+            FallbackSpec::Single(s) if s.is_empty() => Vec::new(),
+            FallbackSpec::Single(s) => vec![s],
+            FallbackSpec::Multiple(v) => v.into_iter().filter(|s| !s.is_empty()).collect(),
+        }
+    }
+}
+
 #[derive(Debug, Clone, Default, Deserialize)]
 pub struct DefaultConfig {
     #[serde(default)]
@@ -30,9 +50,11 @@ pub struct TaskConfig {
     pub max_tokens: Option<u32>,
     #[serde(default)]
     pub description: String,
-    /// Secondary model identifier used if the primary fails.
+    /// Secondary model(s) tried in order on primary failure. Accepts a
+    /// single string (legacy) or an array. Empty (`""` or `[]`) is an
+    /// explicit opt-out and suppresses `defaults.fallback_model`.
     #[serde(default)]
-    pub fallback: Option<String>,
+    pub fallback: Option<FallbackSpec>,
     /// Embedding-only: vector dimensions.
     #[serde(default)]
     pub dimensions: Option<u32>,
@@ -47,10 +69,15 @@ pub struct ModelConfig {
 }
 
 /// Resolved model parameters for an LLM call.
+///
+/// `fallback_model` is intentionally singular-named even though it's a
+/// `Vec<String>`: semantically only ONE fallback is ever used per call
+/// (the chain is tried sequentially, first success wins). Plural naming
+/// would mislead readers into thinking the candidates run in parallel.
 #[derive(Debug, Clone)]
 pub struct ResolvedModel {
     pub model: String,
-    pub fallback_model: Option<String>,
+    pub fallback_model: Vec<String>,
     pub temperature: f64,
     pub max_tokens: u32,
 }
@@ -87,9 +114,13 @@ impl ModelConfig {
             .or_else(|| self.defaults.fallback_model.clone())
             .unwrap_or_else(|| FALLBACK_MODEL.to_string());
 
-        let fallback_model = task_cfg
-            .and_then(|t| t.fallback.clone())
-            .or_else(|| self.defaults.fallback_model.clone());
+        // Precedence: explicit per-task `fallback` (even when empty)
+        // wins over defaults. Only an absent per-task value inherits
+        // the singleton from `[defaults] fallback_model`.
+        let fallback_model: Vec<String> = match task_cfg.and_then(|t| t.fallback.as_ref()) {
+            Some(spec) => spec.clone().into_vec(),
+            None => self.defaults.fallback_model.iter().cloned().collect(),
+        };
 
         let temperature = task_cfg
             .and_then(|t| t.temperature)
@@ -175,6 +206,11 @@ max_tokens = 600
         let cfg = ModelConfig::from_toml_str(SAMPLE).unwrap();
         let r = cfg.resolve("nonexistent_task", None);
         assert_eq!(r.model, "x-ai/grok-4-mini");
+        assert_eq!(
+            r.fallback_model,
+            vec!["x-ai/grok-4-mini".to_string()],
+            "unknown task must inherit defaults.fallback_model as a singleton"
+        );
         assert_eq!(r.temperature, 0.5);
         assert_eq!(r.max_tokens, 200);
     }
@@ -259,8 +295,8 @@ description  = "reserved — Voyage hard-codes its own model"
         let chat = cfg.tasks.get("chat_companion").unwrap();
         assert_eq!(chat.model, "x-ai/grok-4-fast");
         assert_eq!(
-            chat.fallback.as_deref(),
-            Some("deepseek/deepseek-chat-v3.2")
+            chat.fallback.clone().expect("fallback present").into_vec(),
+            vec!["deepseek/deepseek-chat-v3.2".to_string()]
         );
         assert_eq!(chat.temperature, Some(0.85));
         assert_eq!(chat.max_tokens, Some(600));
@@ -270,16 +306,20 @@ description  = "reserved — Voyage hard-codes its own model"
         let insight = cfg.tasks.get("insight_extraction").unwrap();
         assert_eq!(insight.model, "x-ai/grok-4-mini");
         assert_eq!(
-            insight.fallback.as_deref(),
-            Some("deepseek/deepseek-chat-v3.2")
+            insight
+                .fallback
+                .clone()
+                .expect("fallback present")
+                .into_vec(),
+            vec!["deepseek/deepseek-chat-v3.2".to_string()]
         );
         assert_eq!(insight.temperature, Some(0.3));
         assert_eq!(insight.max_tokens, Some(400));
 
         // pde_decision — reserved, partial fields.
         let pde = cfg.tasks.get("pde_decision").unwrap();
         assert_eq!(pde.model, "x-ai/grok-4-mini");
-        assert_eq!(pde.fallback, None);
+        assert!(pde.fallback.is_none());
         assert_eq!(pde.temperature, Some(0.5));
 
         // embedding — reserved, with `dimensions` set.
@@ -291,8 +331,8 @@ description  = "reserved — Voyage hard-codes its own model"
         let r = cfg.resolve("chat_companion", None);
         assert_eq!(r.model, "x-ai/grok-4-fast");
         assert_eq!(
-            r.fallback_model.as_deref(),
-            Some("deepseek/deepseek-chat-v3.2")
+            r.fallback_model,
+            vec!["deepseek/deepseek-chat-v3.2".to_string()]
         );
         assert_eq!(r.temperature, 0.85);
         assert_eq!(r.max_tokens, 600);
@@ -304,4 +344,135 @@ description  = "reserved — Voyage hard-codes its own model"
         assert_eq!(r.temperature, 0.85);
         assert_eq!(r.max_tokens, 600);
     }
+
+    #[test]
+    fn fallback_spec_deserializes_from_string() {
+        let toml = r#"
+[tasks.chat_companion]
+model = "x"
+fallback = "y"
+        "#;
+        let cfg = ModelConfig::from_toml_str(toml).expect("parse ok");
+        let t = cfg.tasks.get("chat_companion").unwrap();
+        let v = t.fallback.clone().expect("fallback present").into_vec();
+        assert_eq!(v, vec!["y".to_string()]);
+    }
+
+    #[test]
+    fn fallback_spec_deserializes_from_array() {
+        let toml = r#"
+[tasks.chat_companion]
+model = "x"
+fallback = ["a", "b"]
+        "#;
+        let cfg = ModelConfig::from_toml_str(toml).expect("parse ok");
+        let t = cfg.tasks.get("chat_companion").unwrap();
+        let v = t.fallback.clone().expect("fallback present").into_vec();
+        assert_eq!(v, vec!["a".to_string(), "b".to_string()]);
+    }
+
+    #[test]
+    fn fallback_spec_skips_empty_entries() {
+        let toml = r#"
+[tasks.chat_companion]
+model = "x"
+fallback = ["", "a", ""]
+        "#;
+        let cfg = ModelConfig::from_toml_str(toml).expect("parse ok");
+        let t = cfg.tasks.get("chat_companion").unwrap();
+        let v = t.fallback.clone().expect("fallback present").into_vec();
+        assert_eq!(v, vec!["a".to_string()]);
+    }
+
+    #[test]
+    fn fallback_spec_empty_string_collapses_to_empty_vec() {
+        let toml = r#"
+[tasks.chat_companion]
+model = "x"
+fallback = ""
+        "#;
+        let cfg = ModelConfig::from_toml_str(toml).expect("parse ok");
+        let t = cfg.tasks.get("chat_companion").unwrap();
+        let v = t.fallback.clone().expect("fallback present").into_vec();
+        assert!(v.is_empty());
+    }
+
+    #[test]
+    fn resolve_returns_empty_fallback_when_no_task_fallback_no_defaults() {
+        let toml = r#"
+[tasks.chat_companion]
+model = "x"
+        "#;
+        let cfg = ModelConfig::from_toml_str(toml).expect("parse ok");
+        let r = cfg.resolve("chat_companion", None);
+        assert_eq!(r.model, "x");
+        assert!(r.fallback_model.is_empty());
+    }
+
+    #[test]
+    fn resolve_returns_defaults_fallback_when_task_has_none() {
+        let toml = r#"
+[defaults]
+fallback_model = "default-fb"
+
+[tasks.chat_companion]
+model = "x"
+        "#;
+        let cfg = ModelConfig::from_toml_str(toml).expect("parse ok");
+        let r = cfg.resolve("chat_companion", None);
+        assert_eq!(r.fallback_model, vec!["default-fb".to_string()]);
+    }
+
+    #[test]
+    fn resolve_task_array_overrides_defaults() {
+        let toml = r#"
+[defaults]
+fallback_model = "default-fb"
+
+[tasks.chat_companion]
+model = "x"
+fallback = ["a", "b"]
+        "#;
+        let cfg = ModelConfig::from_toml_str(toml).expect("parse ok");
+        let r = cfg.resolve("chat_companion", None);
+        assert_eq!(r.fallback_model, vec!["a".to_string(), "b".to_string()]);
+    }
+
+    #[test]
+    fn resolve_empty_array_suppresses_defaults() {
+        let toml = r#"
+[defaults]
+fallback_model = "default-fb"
+
+[tasks.chat_companion]
+model = "x"
+fallback = []
+        "#;
+        let cfg = ModelConfig::from_toml_str(toml).expect("parse ok");
+        let r = cfg.resolve("chat_companion", None);
+        assert!(
+            r.fallback_model.is_empty(),
+            "explicit empty array must suppress defaults; got {:?}",
+            r.fallback_model
+        );
+    }
+
+    #[test]
+    fn resolve_empty_string_suppresses_defaults() {
+        let toml = r#"
+[defaults]
+fallback_model = "default-fb"
+
+[tasks.chat_companion]
+model = "x"
+fallback = ""
+        "#;
+        let cfg = ModelConfig::from_toml_str(toml).expect("parse ok");
+        let r = cfg.resolve("chat_companion", None);
+        assert!(
+            r.fallback_model.is_empty(),
+            "explicit empty string must suppress defaults; got {:?}",
+            r.fallback_model
+        );
+    }
 }