create-workframe 0.1.1 → 0.1.3

package/scripts/verify-public-deploy.sh

@@ -1,105 +1,105 @@
-#!/usr/bin/env bash
-# Fail-closed preflight for WORKFRAME_DEPLOYMENT_MODE=public_multi_user.
-# Usage: bash scripts/workframe/verify-public-deploy.sh [compose-dir]
-set -euo pipefail
-
-ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
-COMPOSE_DIR="${1:-$ROOT/infra/compose/workframe}"
-ENV_FILE="$COMPOSE_DIR/.env"
-COMPOSE_FILE="$COMPOSE_DIR/docker-compose.yml"
-
-fail() { echo "FAIL: $*" >&2; exit 1; }
-warn() { echo "WARN: $*" >&2; }
-ok() { echo "OK: $*"; }
-
-[[ -f "$ENV_FILE" ]] || fail "missing $ENV_FILE"
-[[ -f "$COMPOSE_FILE" ]] || fail "missing $COMPOSE_FILE"
-
-env_val() {
-  local key="$1"
-  grep -E "^${key}=" "$ENV_FILE" | tail -n1 | cut -d= -f2- | tr -d '\r' || true
-}
-
-MODE="$(env_val WORKFRAME_DEPLOYMENT_MODE)"
-MODE="${MODE:-trusted_team}"
-if [[ "$MODE" != "public_multi_user" ]]; then
-  ok "WORKFRAME_DEPLOYMENT_MODE=$MODE (skipping public checks; pass nothing to force public)"
-  exit 0
-fi
-
-ok "checking public_multi_user preflight"
-
-if [[ "$(env_val DEV_LOCAL_UNSAFE)" =~ ^(1|true|yes|on)$ ]]; then
-  fail "DEV_LOCAL_UNSAFE must be off for public_multi_user"
-fi
-if [[ "$(env_val SECURE_MODE)" != "true" ]]; then
-  fail "SECURE_MODE=true required"
-fi
-
-for key in WORKFRAME_SUPERVISOR_TOKEN WORKFRAME_API_TOKEN WORKFRAME_PROXY_TOKEN WORKFRAME_VAULT_KEK \
-  ZK_AUTH_HMAC_KEY ZK_AUTH_ENCRYPTION_KEY ZK_AUTH_SESSION_SECRET \
-  SMTP_HOST SMTP_USER SMTP_PASS EMAIL_FROM; do
-  [[ -n "$(env_val "$key")" ]] || fail "$key is empty"
-done
-
-APP_URL="$(env_val APP_BASE_URL)"
-[[ "$APP_URL" == https://* ]] || fail "APP_BASE_URL must be https:// (got ${APP_URL:-<empty>})"
-
-enc_key="$(env_val ZK_AUTH_ENCRYPTION_KEY)"
-if [[ -n "$enc_key" ]]; then
-  python3 - "$enc_key" <<'PY' || fail "ZK_AUTH_ENCRYPTION_KEY must be base64-encoded 32 bytes (not hex)"
-import base64, sys
-raw = base64.b64decode(sys.argv[1].strip())
-assert len(raw) == 32
-PY
-  ok "ZK_AUTH_ENCRYPTION_KEY format"
-fi
-
-if [[ "$(env_val WORKFRAME_E2E)" =~ ^(1|true|yes|on)$ ]] && [[ "$APP_URL" == https://* ]]; then
-  fail "WORKFRAME_E2E must be off for public HTTPS deploy"
-fi
-
-if grep -A40 '^  gateway:' "$COMPOSE_FILE" | grep -q 'env_file:'; then
-  fail "gateway must not use env_file in docker-compose.yml"
-fi
-if ! grep -q 'control-net' "$COMPOSE_FILE"; then
-  fail "control-net missing from docker-compose.yml"
-fi
-
-UI_PORT="$(env_val WORKFRAME_UI_PORT)"
-UI_PORT="${UI_PORT:-18644}"
-API_PORT="$(env_val WORKFRAME_API_PORT)"
-API_PORT="${API_PORT:-19120}"
-
-if command -v curl >/dev/null 2>&1; then
-  health="$(curl -fsS "http://127.0.0.1:${API_PORT}/api/health" 2>/dev/null || true)"
-  if [[ -z "$health" ]]; then
-    warn "API health unreachable on 127.0.0.1:${API_PORT} (stack down?)"
-  else
-    echo "$health" | grep -q 'public_multi_user' || fail "API health missing deployment_mode public_multi_user"
-    echo "$health" | grep -q '"mode": "secure"' || fail "API not in secure mode"
-    echo "$health" | grep -q '"proxy_token_configured": true' || fail "API proxy_token_configured is false"
-    echo "$health" | grep -q '"vault_envelope": true' || fail "API vault_envelope is false"
-    echo "$health" | grep -q '"docker_sock_on_api": false' || fail "API still has docker.sock mounted"
-    echo "$health" | grep -q 'install_window_open' || warn "API health missing install_window_open"
-    echo "$health" | grep -q 'workframe_e2e' || warn "API health missing workframe_e2e"
-    echo "$health" | grep -q 'dev_local_unsafe' || warn "API health missing dev_local_unsafe"
-    ok "API health"
-  fi
-  dash_code="$(curl -sS -o /dev/null -w '%{http_code}' "http://127.0.0.1:${UI_PORT}/hermes-dashboard/" || true)"
-  [[ "$dash_code" == "403" ]] || warn "hermes-dashboard without session returned $dash_code (expected 403)"
-else
-  warn "curl not found — skipping HTTP checks"
-fi
-
-if command -v docker >/dev/null 2>&1 && docker inspect workframe-gateway >/dev/null 2>&1; then
-  gw_env="$(docker inspect workframe-gateway --format '{{range .Config.Env}}{{println .}}{{end}}')"
-  for marker in WORKFRAME_SUPERVISOR_TOKEN ZK_AUTH_ SMTP_PASS; do
-    echo "$gw_env" | grep -q "$marker" && fail "gateway env contains $marker"
-  done
-  ok "gateway env allowlist"
-else
-  warn "workframe-gateway not running — skipping docker inspect"
-fi
-
-ok "public_multi_user preflight passed"
+#!/usr/bin/env bash
+# Fail-closed preflight for WORKFRAME_DEPLOYMENT_MODE=public_multi_user.
+# Usage: bash scripts/workframe/verify-public-deploy.sh [compose-dir]
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+COMPOSE_DIR="${1:-$ROOT/infra/compose/workframe}"
+ENV_FILE="$COMPOSE_DIR/.env"
+COMPOSE_FILE="$COMPOSE_DIR/docker-compose.yml"
+
+fail() { echo "FAIL: $*" >&2; exit 1; }
+warn() { echo "WARN: $*" >&2; }
+ok() { echo "OK: $*"; }
+
+[[ -f "$ENV_FILE" ]] || fail "missing $ENV_FILE"
+[[ -f "$COMPOSE_FILE" ]] || fail "missing $COMPOSE_FILE"
+
+env_val() {
+  local key="$1"
+  grep -E "^${key}=" "$ENV_FILE" | tail -n1 | cut -d= -f2- | tr -d '\r' || true
+}
+
+MODE="$(env_val WORKFRAME_DEPLOYMENT_MODE)"
+MODE="${MODE:-trusted_team}"
+if [[ "$MODE" != "public_multi_user" ]]; then
+  ok "WORKFRAME_DEPLOYMENT_MODE=$MODE (skipping public checks; pass nothing to force public)"
+  exit 0
+fi
+
+ok "checking public_multi_user preflight"
+
+if [[ "$(env_val DEV_LOCAL_UNSAFE)" =~ ^(1|true|yes|on)$ ]]; then
+  fail "DEV_LOCAL_UNSAFE must be off for public_multi_user"
+fi
+if [[ "$(env_val SECURE_MODE)" != "true" ]]; then
+  fail "SECURE_MODE=true required"
+fi
+
+for key in WORKFRAME_SUPERVISOR_TOKEN WORKFRAME_API_TOKEN WORKFRAME_PROXY_TOKEN WORKFRAME_VAULT_KEK \
+  ZK_AUTH_HMAC_KEY ZK_AUTH_ENCRYPTION_KEY ZK_AUTH_SESSION_SECRET \
+  SMTP_HOST SMTP_USER SMTP_PASS EMAIL_FROM; do
+  [[ -n "$(env_val "$key")" ]] || fail "$key is empty"
+done
+
+APP_URL="$(env_val APP_BASE_URL)"
+[[ "$APP_URL" == https://* ]] || fail "APP_BASE_URL must be https:// (got ${APP_URL:-<empty>})"
+
+enc_key="$(env_val ZK_AUTH_ENCRYPTION_KEY)"
+if [[ -n "$enc_key" ]]; then
+  python3 - "$enc_key" <<'PY' || fail "ZK_AUTH_ENCRYPTION_KEY must be base64-encoded 32 bytes (not hex)"
+import base64, sys
+raw = base64.b64decode(sys.argv[1].strip())
+assert len(raw) == 32
+PY
+  ok "ZK_AUTH_ENCRYPTION_KEY format"
+fi
+
+if [[ "$(env_val WORKFRAME_E2E)" =~ ^(1|true|yes|on)$ ]] && [[ "$APP_URL" == https://* ]]; then
+  fail "WORKFRAME_E2E must be off for public HTTPS deploy"
+fi
+
+if grep -A40 '^  gateway:' "$COMPOSE_FILE" | grep -q 'env_file:'; then
+  fail "gateway must not use env_file in docker-compose.yml"
+fi
+if ! grep -q 'control-net' "$COMPOSE_FILE"; then
+  fail "control-net missing from docker-compose.yml"
+fi
+
+UI_PORT="$(env_val WORKFRAME_UI_PORT)"
+UI_PORT="${UI_PORT:-18644}"
+API_PORT="$(env_val WORKFRAME_API_PORT)"
+API_PORT="${API_PORT:-19120}"
+
+if command -v curl >/dev/null 2>&1; then
+  health="$(curl -fsS "http://127.0.0.1:${API_PORT}/api/health" 2>/dev/null || true)"
+  if [[ -z "$health" ]]; then
+    warn "API health unreachable on 127.0.0.1:${API_PORT} (stack down?)"
+  else
+    echo "$health" | grep -q 'public_multi_user' || fail "API health missing deployment_mode public_multi_user"
+    echo "$health" | grep -q '"mode": "secure"' || fail "API not in secure mode"
+    echo "$health" | grep -q '"proxy_token_configured": true' || fail "API proxy_token_configured is false"
+    echo "$health" | grep -q '"vault_envelope": true' || fail "API vault_envelope is false"
+    echo "$health" | grep -q '"docker_sock_on_api": false' || fail "API still has docker.sock mounted"
+    echo "$health" | grep -q 'install_window_open' || warn "API health missing install_window_open"
+    echo "$health" | grep -q 'workframe_e2e' || warn "API health missing workframe_e2e"
+    echo "$health" | grep -q 'dev_local_unsafe' || warn "API health missing dev_local_unsafe"
+    ok "API health"
+  fi
+  dash_code="$(curl -sS -o /dev/null -w '%{http_code}' "http://127.0.0.1:${UI_PORT}/hermes-dashboard/" || true)"
+  [[ "$dash_code" == "403" ]] || warn "hermes-dashboard without session returned $dash_code (expected 403)"
+else
+  warn "curl not found — skipping HTTP checks"
+fi
+
+if command -v docker >/dev/null 2>&1 && docker inspect workframe-gateway >/dev/null 2>&1; then
+  gw_env="$(docker inspect workframe-gateway --format '{{range .Config.Env}}{{println .}}{{end}}')"
+  for marker in WORKFRAME_SUPERVISOR_TOKEN ZK_AUTH_ SMTP_PASS; do
+    echo "$gw_env" | grep -q "$marker" && fail "gateway env contains $marker"
+  done
+  ok "gateway env allowlist"
+else
+  warn "workframe-gateway not running — skipping docker inspect"
+fi
+
+ok "public_multi_user preflight passed"

package/workframe-api/README.md

@@ -1,28 +1,24 @@
 # Workframe API Service
 
-**Version:** `0.1.0` (`workframe-api-0.1.0`). See `docs/VERSION.md`.
+HTTP API for the Workframe UI. See [docs/VERSION.md](../../docs/VERSION.md) for release version.
 
-Active backend service for the transplanted Workframe vertical slice.
-
-This is intentionally preserved as the current Python BFF instead of being rewritten into `apps/api`.
-
-## Local
+## Local (outside Docker)
 
 ```bash
 cd services/workframe-api
 python3 -m venv .venv
-. .venv/bin/activate
+. .venv/bin/activate   # Windows: .venv\Scripts\activate
 pip install -r requirements.txt
 HOST=0.0.0.0 PORT=8080 HERMES_DATA=/opt/data WORKSPACE=/workspace python3 server.py
 ```
 
-## Runtime state
+## Runtime state (not committed)
 
-Runtime files are intentionally not committed:
+- `data/*.db`, vault files under `WORKFRAME_API_DATA_DIR`
+- Hermes `Agents/` tree on mounted volume
 
-- `data/*.db`
-- `data/.auth_keys`
-- Hermes `Agents/`
-- workspace `Files/`
+## Docs
 
-For VPS deployment, mount clean persistent volumes into `/opt/data` and `/workspace`.
+- [Operations](../../docs/public/operations.md)
+- [Security](../../docs/public/security.md)
+- [API reference](../../docs/public/api-reference.md)

package/workframe-api/concierge.py

@@ -0,0 +1,173 @@
+"""Deterministic concierge when LLM is unavailable — keyword intent router, no LLM."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+import llm_error_glossary as glossary
+
+# ponytail: (intent_id, patterns) — first match wins
+_INTENTS: list[tuple[str, tuple[str, ...]]] = [
+    (
+        "add_provider_keys",
+        (
+            "add key",
+            "add keys",
+            "api key",
+            "connect openrouter",
+            "connect provider",
+            "where key",
+            "how do i connect",
+            "how to connect",
+            "openrouter key",
+            "llm key",
+            "provider key",
+        ),
+    ),
+    (
+        "change_model",
+        (
+            "set model",
+            "change model",
+            "pick model",
+            "which model",
+            "how do i set model",
+            "how to set model",
+            "choose model",
+            "switch model",
+            "model picker",
+        ),
+    ),
+    (
+        "provider_credits",
+        (
+            "out of credit",
+            "no credit",
+            "add credit",
+            "billing",
+            "top up",
+            "purchase credit",
+        ),
+    ),
+    (
+        "invalid_key",
+        (
+            "invalid key",
+            "key rejected",
+            "bad key",
+            "wrong key",
+            "401",
+            "unauthorized",
+        ),
+    ),
+    (
+        "diagnose",
+        (
+            "what's wrong",
+            "whats wrong",
+            "why no reply",
+            "not working",
+            "not replying",
+            "help me",
+            "what happened",
+        ),
+    ),
+    (
+        "getting_started",
+        (
+            "get started",
+            "how do i start",
+            "how to start",
+            "new here",
+            "first time",
+        ),
+    ),
+]
+
+_INTENT_PLAYBOOK: dict[str, dict[str, Any]] = {
+    "add_provider_keys": {
+        "message": "Connect an LLM provider to enable chat.",
+        "hint": "OpenRouter is the fastest path — paste your API key under Connected accounts.",
+        "action": {"type": "open_settings", "tab": "providers"},
+        "action_label": "Add API key",
+        "code": "concierge_add_keys",
+    },
+    "change_model": {
+        "message": "Choose which model this agent uses.",
+        "hint": "Open the model picker and select a model your provider supports.",
+        "action": {"type": "open_settings", "tab": "model"},
+        "action_label": "Choose model",
+        "code": "concierge_change_model",
+    },
+    "provider_credits": glossary.playbook_entry("provider_no_credits"),
+    "invalid_key": glossary.playbook_entry("provider_invalid_key"),
+    "diagnose": {
+        "message": "I can help you troubleshoot setup.",
+        "hint": "Connect a provider first, then pick a live model. If chat still fails, check credits and the model name.",
+        "action": {"type": "open_settings", "tab": "providers"},
+        "action_label": "Connected accounts",
+        "secondary_action": {"type": "open_settings", "tab": "model"},
+        "secondary_action_label": "Choose model",
+        "code": "concierge_diagnose",
+    },
+    "getting_started": {
+        "message": "Welcome to Workframe. Three steps to your first agent reply:",
+        "hint": "1) Connect an LLM provider · 2) Pick a model · 3) Send a message in chat.",
+        "action": {"type": "open_settings", "tab": "providers"},
+        "action_label": "Connect provider",
+        "code": "concierge_getting_started",
+    },
+    "fallback_help": glossary.playbook_entry("no_llm_provider"),
+}
+
+
+def _normalize(text: str) -> str:
+    return re.sub(r"\s+", " ", str(text or "").lower().strip())
+
+
+def match_intent(user_text: str) -> str:
+    norm = _normalize(user_text)
+    if not norm:
+        return "fallback_help"
+    for intent_id, patterns in _INTENTS:
+        for pat in patterns:
+            if pat in norm:
+                return intent_id
+    return "fallback_help"
+
+
+def respond(
+    user_text: str,
+    *,
+    situation: str = "",
+    last_error: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Return concierge playbook for user message or classified error."""
+    if last_error and str(last_error.get("code") or "") not in ("", "concierge"):
+        entry = dict(last_error)
+        entry.setdefault("message", entry.get("text") or "")
+        hint = str(entry.get("hint") or "").strip()
+        if hint:
+            entry["hint"] = f"{hint} You can also ask how to connect keys or change models."
+        return glossary.notice_payload(entry)
+
+    if situation == "no_provider":
+        intent = match_intent(user_text)
+        if intent == "fallback_help":
+            return glossary.notice_payload(_INTENT_PLAYBOOK["getting_started"])
+        return glossary.notice_payload(_INTENT_PLAYBOOK.get(intent) or _INTENT_PLAYBOOK["fallback_help"])
+
+    intent = match_intent(user_text)
+    row = dict(_INTENT_PLAYBOOK.get(intent) or _INTENT_PLAYBOOK["fallback_help"])
+    return glossary.notice_payload(row)
+
+
+if __name__ == "__main__":
+    r = respond("how do I add keys?", situation="no_provider")
+    assert r["code"] == "concierge_add_keys"
+    r2 = respond("how do I set model?", situation="no_provider")
+    assert r2["code"] == "concierge_change_model"
+    r3 = respond("hello", situation="no_provider")
+    assert r3["code"] == "concierge_getting_started"
+    print("concierge ok")

package/workframe-api/llm_error_glossary.py

@@ -0,0 +1,236 @@
+"""Classify LLM/provider failures into didactic copy + UI actions."""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+
+# ponytail: static playbook — extend rows, no LLM generation
+_ACTIONS: dict[str, dict[str, Any]] = {
+    "open_providers": {"type": "open_settings", "tab": "providers"},
+    "open_model": {"type": "open_settings", "tab": "model"},
+    "retry": {"type": "retry"},
+    "openrouter_credits": {
+        "type": "external_link",
+        "url": "https://openrouter.ai/credits",
+        "label": "Add credits",
+    },
+    "openrouter_keys": {
+        "type": "external_link",
+        "url": "https://openrouter.ai/keys",
+        "label": "Manage keys",
+    },
+}
+
+PLAYBOOK: dict[str, dict[str, Any]] = {
+    "no_llm_provider": {
+        "message": "No model provider is connected for your account yet.",
+        "hint": "Connect OpenRouter or another LLM provider under Connected accounts, then try again.",
+        "action": _ACTIONS["open_providers"],
+        "action_label": "Connect provider",
+    },
+    "provider_invalid_key": {
+        "message": "Your API key was rejected by the provider.",
+        "hint": "Reset the key at your provider, then paste it again under Connected accounts.",
+        "action": _ACTIONS["open_providers"],
+        "action_label": "Update API key",
+        "secondary_action": _ACTIONS["openrouter_keys"],
+        "secondary_action_label": "Open provider keys",
+    },
+    "provider_no_credits": {
+        "message": "Your provider account has no credits remaining.",
+        "hint": "Add credits at your provider billing page, then send your message again.",
+        "action": _ACTIONS["openrouter_credits"],
+        "action_label": "Add credits",
+        "secondary_action": _ACTIONS["open_model"],
+        "secondary_action_label": "Choose another model",
+    },
+    "model_unavailable": {
+        "message": "The selected model is not available on your provider right now.",
+        "hint": "Pick a different model in Settings. Free models on OpenRouter rotate often.",
+        "action": _ACTIONS["open_model"],
+        "action_label": "Choose model",
+    },
+    "model_invalid_id": {
+        "message": "That model ID is not valid for your provider.",
+        "hint": "Open the model picker and select a model from the list, or type a known provider/model id.",
+        "action": _ACTIONS["open_model"],
+        "action_label": "Choose model",
+    },
+    "provider_rate_limited": {
+        "message": "The provider rate-limited this request.",
+        "hint": "Wait a minute or switch to another model.",
+        "action": _ACTIONS["open_model"],
+        "action_label": "Choose model",
+    },
+    "invalid_lease": {
+        "message": "Your session credential expired before the model replied.",
+        "hint": "Send the message again — Workframe will issue a fresh credential.",
+        "action": _ACTIONS["retry"],
+        "action_label": "Try again",
+    },
+    "provider_empty_reply": {
+        "message": "The model provider returned no reply.",
+        "hint": "Check your API key, credits, and model selection in Settings.",
+        "action": _ACTIONS["open_model"],
+        "action_label": "Check model",
+        "secondary_action": _ACTIONS["open_providers"],
+        "secondary_action_label": "Check API key",
+    },
+    "provider_gateway_error": {
+        "message": "Workframe could not reach the model gateway.",
+        "hint": "Confirm the stack is running and try again.",
+        "action": _ACTIONS["retry"],
+        "action_label": "Try again",
+    },
+    "unknown_provider_error": {
+        "message": "The model request failed.",
+        "hint": "Check Connected accounts and the model in Settings.",
+        "action": _ACTIONS["open_providers"],
+        "action_label": "Connected accounts",
+        "secondary_action": _ACTIONS["open_model"],
+        "secondary_action_label": "Choose model",
+    },
+}
+
+
+def playbook_entry(code: str, **overrides: Any) -> dict[str, Any]:
+    """Return a copy of a playbook row with optional string format overrides."""
+    base = dict(PLAYBOOK.get(code) or PLAYBOOK["unknown_provider_error"])
+    base["code"] = code
+    for key, value in overrides.items():
+        if value is not None and key in base and isinstance(base[key], str):
+            try:
+                base[key] = base[key].format(**overrides)
+            except (KeyError, ValueError):
+                base[key] = str(value)
+        elif value is not None:
+            base[key] = value
+    return base
+
+
+def _parse_json_blob(raw: str) -> dict[str, Any] | None:
+    text = str(raw or "").strip()
+    if not text or text[0] not in "{[":
+        return None
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError:
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def _extract_error_message(data: dict[str, Any] | None, raw: str = "") -> str:
+    if data:
+        err = data.get("error")
+        if isinstance(err, dict):
+            msg = str(err.get("message") or "").strip()
+            if msg:
+                return msg
+        if isinstance(err, str) and err.strip():
+            return err.strip()
+        for key in ("message", "detail"):
+            val = data.get(key)
+            if isinstance(val, str) and val.strip():
+                return val.strip()
+    return str(raw or "").strip()
+
+
+def _model_from_text(text: str) -> str:
+    m = re.search(r"for\s+([a-z0-9_.:/-]+)", text, re.I)
+    return m.group(1) if m else ""
+
+
+def classify_upstream(
+    status: int,
+    body: bytes | str | None = None,
+    *,
+    provider: str = "openrouter",
+    model: str = "",
+) -> dict[str, Any]:
+    """Map upstream HTTP status + body to playbook entry."""
+    raw = body.decode("utf-8", errors="replace") if isinstance(body, (bytes, bytearray)) else str(body or "")
+    data = _parse_json_blob(raw)
+    msg = _extract_error_message(data, raw)
+    low = msg.lower()
+    model_id = model or _model_from_text(msg)
+
+    if status == 401 or "invalid api key" in low or "incorrect api key" in low or "unauthorized" in low:
+        return playbook_entry("provider_invalid_key", provider=provider)
+    if status == 402 or "insufficient" in low and "credit" in low or "payment required" in low:
+        return playbook_entry("provider_no_credits", provider=provider)
+    if status == 429 or "rate limit" in low:
+        return playbook_entry("provider_rate_limited", provider=provider)
+    if status == 400 and ("not a valid model" in low or "invalid model" in low):
+        entry = playbook_entry("model_invalid_id", model=model_id or "selected model")
+        if model_id:
+            entry["message"] = f"Model `{model_id}` is not a valid id on {provider}."
+        return entry
+    if status == 404 or "no endpoints found" in low or "model not found" in low:
+        entry = playbook_entry("model_unavailable", model=model_id or "selected model")
+        if model_id:
+            entry["message"] = f"Model `{model_id}` has no live endpoints on {provider} right now."
+        return entry
+    if status >= 500:
+        return playbook_entry("provider_gateway_error", provider=provider)
+    return playbook_entry("unknown_provider_error", provider=provider, detail=msg[:200] if msg else "")
+
+
+def classify_exception_text(text: str) -> dict[str, Any]:
+    raw = str(text or "").strip()
+    if not raw:
+        return playbook_entry("provider_empty_reply")
+    if "no_llm_provider_for_user" in raw:
+        return playbook_entry("no_llm_provider")
+    if "invalid_lease" in raw or "credential expired" in raw.lower():
+        return playbook_entry("invalid_lease")
+    m = re.search(r"HTTP (\d{3})", raw)
+    if m:
+        return classify_upstream(int(m.group(1)), raw)
+    low = raw.lower()
+    if "no endpoints found" in low or "model" in low and "not found" in low:
+        return classify_upstream(404, raw)
+    if "not a valid model" in low:
+        return classify_upstream(400, raw)
+    if "rate limit" in low:
+        return classify_upstream(429, raw)
+    if "credit" in low:
+        return classify_upstream(402, raw)
+    if "api key" in low or "unauthorized" in low:
+        return classify_upstream(401, raw)
+    return playbook_entry("unknown_provider_error", detail=raw[:200])
+
+
+def notice_payload(entry: dict[str, Any]) -> dict[str, Any]:
+    """SSE/JSON-safe dict for UI."""
+    out: dict[str, Any] = {
+        "code": str(entry.get("code") or "unknown_provider_error"),
+        "message": str(entry.get("message") or ""),
+        "hint": str(entry.get("hint") or ""),
+        "text": str(entry.get("message") or ""),
+        "error": str(entry.get("message") or ""),
+    }
+    action = entry.get("action")
+    if isinstance(action, dict):
+        out["action"] = action
+    label = entry.get("action_label")
+    if label:
+        out["action_label"] = str(label)
+    sec = entry.get("secondary_action")
+    if isinstance(sec, dict):
+        out["secondary_action"] = sec
+    sec_label = entry.get("secondary_action_label")
+    if sec_label:
+        out["secondary_action_label"] = str(sec_label)
+    return out
+
+
+if __name__ == "__main__":
+    e = classify_upstream(404, b'{"error":{"message":"No endpoints found for openrouter/owl-alpha."}}', model="openrouter/owl-alpha")
+    assert e["code"] == "model_unavailable"
+    e2 = classify_exception_text("no_llm_provider_for_user: Connect an LLM provider")
+    assert e2["code"] == "no_llm_provider"
+    e3 = classify_upstream(401, b'{"error":"Invalid API key"}')
+    assert e3["code"] == "provider_invalid_key"
+    print("llm_error_glossary ok")

package/workframe-api/llm_proxy.py

@@ -144,6 +144,9 @@ def _build_upstream_request(
         }
     }
     upstream_headers.update(upstream_auth_header(provider, secret))
+    if provider == "openrouter":
+        upstream_headers.setdefault("HTTP-Referer", "https://workfra.me")
+        upstream_headers.setdefault("X-Title", "Workframe")
 
     req = urllib.request.Request(url, data=body, headers=upstream_headers, method=method.upper())
     return req, None