@zerwiz/ymir 0.1.4 → 0.1.7

package/bin/agents-config.sh

@@ -0,0 +1,256 @@
+#!/usr/bin/env bash
+# agents-config.sh — one YAML for the Allfather's agent/harness/model combination.
+#
+#   bin/agents-config.sh show                 # the current combination (TOON)
+#   bin/agents-config.sh get <agent> <key>    # key: harness | model
+#   bin/agents-config.sh resolve              # exact ids for local provider models
+#   bin/agents-config.sh init                 # seed config/agents.yaml from the template
+#   bin/agents-config.sh apply                # write it into agents + project config
+#   bin/agents-config.sh --version
+#
+# Source of truth: config/agents.yaml. `apply` sets `model:` in the canonical
+# `.agents/agents/*.md` (matched by `name:`), writes local providers + agent
+# models into project `opencode.json`, emits a runnable primary for any agent
+# marked `primary: true`, and caches the resolved combination in
+# `state/agents-resolved.json` (read by `get` and bin/agent-run.sh).
+set -u
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+# The operator's settings and secrets live in the home they chose, never in the
+# code tree — a packaged install replaces its tree on upgrade, and a credential
+# must never sit in a tree that ships (Rule 04).
+if [ -z "${YMIR_HOARD_LIB_LOADED:-}" ]; then
+  _yr="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  for _yc in "$_yr/hoard-lib.sh" "$(dirname "$_yr")/bin/hoard-lib.sh"; do
+    [ -r "$_yc" ] && { . "$_yc"; YMIR_HOARD_LIB_LOADED=1; break; }
+  done
+  unset _yr _yc
+fi
+hoard_settings_dir YMIR_SETTINGS_DIR
+hoard_local_env YMIR_ENV_FILE
+CFG="${YMIR_AGENTS_YAML:-$YMIR_SETTINGS_DIR/agents.yaml}"
+RESOLVED="${YMIR_STATE_DIR}/agents-resolved.json"
+
+case "${1-}" in
+  -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;;
+  -h|--help|"") sed -n '2,13p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+esac
+ACTION="${1:-show}"; shift || true
+
+# init — seed the private setup from the tracked template (idempotent).
+if [ "$ACTION" = init ]; then
+  if [ -r "$CFG" ]; then
+    printf 'agents-config[1]{action,state}:\n  "init","kept — %s already exists"\n' "$CFG"
+    exit 0
+  fi
+  TPL="$ROOT/config/agents.yaml.example"
+  [ -r "$TPL" ] || TPL="$ROOT/.agents/config/agents.yaml.example"
+  [ -r "$TPL" ] || { printf 'error: template missing: %s\n' "$TPL" >&2; exit 1; }
+  mkdir -p "$(dirname "$CFG")" 2>/dev/null || true
+  cp "$TPL" "$CFG" || { printf 'error: could not write %s\n' "$CFG" >&2; exit 1; }
+  printf 'agents-config[1]{action,path}:\n  "init","%s"\n' "$CFG"
+  exit 0
+fi
+
+
+[ -r "$CFG" ] || { printf 'error: config not found: %s\nhelp: create %s\n' "$CFG" "$CFG" >&2; exit 1; }
+
+python3 - "$ROOT" "$CFG" "$RESOLVED" "$ACTION" "$@" <<'PY'
+import sys, os, json, glob, re, urllib.request
+root, cfg_path, resolved_path, action = sys.argv[1:5]
+args = sys.argv[5:]
+try:
+    import yaml
+except Exception:
+    print('error: python3 has no PyYAML'); sys.exit(1)
+
+cfg = yaml.safe_load(open(cfg_path)) or {}
+
+# Per-machine overlay: config/agents.<hostname>.yaml (private) deep-merges over
+# the base, so one repo runs different models/harness on different machines.
+import socket
+_host = (os.environ.get("YMIR_AGENTS_MACHINE") or socket.gethostname()).split(".")[0]
+_overlay = os.path.join(os.path.dirname(cfg_path), f"agents.{_host}.yaml")
+if os.path.exists(_overlay):
+    def _merge(a, b):
+        for k, v in (b or {}).items():
+            if isinstance(v, dict) and isinstance(a.get(k), dict):
+                _merge(a[k], v)
+            else:
+                a[k] = v
+        return a
+    cfg = _merge(cfg, yaml.safe_load(open(_overlay)) or {})
+default_model   = cfg.get("default_model") or ""
+default_harness = cfg.get("default_harness") or "opencode"
+agents    = cfg.get("agents") or {}
+providers = cfg.get("providers") or {}
+
+def spec_of(a):
+    return agents.get(a) if isinstance(agents.get(a), dict) else {"model": agents.get(a)}
+
+def model_of(a):
+    return spec_of(a).get("model") or default_model
+
+hcfg = cfg.get("harness") or {}
+local_harness   = hcfg.get("local") or "pi"
+online_harness  = hcfg.get("online") or "opencode"
+local_providers = set(hcfg.get("local_providers") or [])
+prov_map        = hcfg.get("providers") or {}
+
+def is_local(a):
+    return model_of(a).split("/", 1)[0] in local_providers
+
+def harness_of(a):
+    return spec_of(a).get("harness") or (local_harness if is_local(a) else online_harness)
+
+def harness_model(a):
+    """The model string as the chosen harness expects it (provider renamed for pi)."""
+    h = harness_of(a)
+    m = resolve_model(model_of(a))
+    prov, _, short = m.partition("/")
+    if h in ("pi", "hermes"):
+        return f"{prov_map.get(prov, {}).get(h, prov)}/{short}"
+    return m
+
+# --- exact-id resolution for local routers -------------------------------
+def server_ids(base_url):
+    """The ids a server reports at <base_url>/models (base_url ends with /v1)."""
+    try:
+        with urllib.request.urlopen(base_url.rstrip("/") + "/models", timeout=4) as r:
+            d = json.load(r)
+        return [m.get("id") for m in (d.get("data") or []) if m.get("id")]
+    except Exception:
+        return []
+
+def resolve_map():
+    """provider -> {alias: exact_id} for any model that is not an exact id."""
+    out = {}
+    for pname, pspec in providers.items():
+        base = pspec.get("base_url")
+        if not base:
+            continue
+        ids = server_ids(base)
+        for mid in (pspec.get("models") or []):
+            if mid in ids:
+                out.setdefault(pname, {})[mid] = mid
+                continue
+            cands = [i for i in ids if i.split("@")[0] == mid]
+            if len(cands) == 1:
+                out.setdefault(pname, {})[mid] = cands[0]
+    return out
+
+def resolve_model(m):
+    """Expand a bare `provider/alias` to the provider's exact served id."""
+    if "/" not in m:
+        return m
+    p, _, short = m.partition("/")
+    exact = resolve_map().get(p, {}).get(short)
+    return f"{p}/{exact}" if exact else m
+
+# --- actions -------------------------------------------------------------
+if action == "show":
+    rows = sorted(agents)
+    print(f'agents-config[{len(rows)}]{{agent,harness,model}}:')
+    for a in rows:
+        print(f'  "{a}","{harness_of(a)}","{harness_model(a)}"')
+    sys.exit(0)
+
+if action == "resolve":
+    changed = []
+    for a in sorted(agents):
+        m = model_of(a); r = resolve_model(m)
+        if r != m:
+            changed.append(f"{a}: {m} -> {r}")
+    if changed:
+        print(f'agents-resolve[{len(changed)}]{{agent,from,to}}:')
+        for c in changed:
+            a, rest = c.split(": ", 1); frm, to = rest.split(" -> ")
+            print(f'  "{a}","{frm}","{to}"')
+    else:
+        print('agents-resolve[1]{state}:\n  "all models are exact ids"')
+    sys.exit(0)
+
+if action == "get":
+    if len(args) < 2:
+        print('error: get needs <agent> <harness|model>'); sys.exit(2)
+    a, key = args[0], args[1]
+    if os.path.exists(resolved_path):
+        try:
+            cached = json.load(open(resolved_path)).get(a, {})
+            if key in cached:
+                print(cached[key]); sys.exit(0)
+        except Exception:
+            pass
+    print(harness_of(a) if key == "harness" else harness_model(a))
+    sys.exit(0)
+
+if action != "apply":
+    print(f'error: unknown action {action}'); sys.exit(2)
+
+changed = []
+rmap = resolve_map()
+
+# 1. Canonical agent profiles — set `model:` where `name:` matches.
+for p in sorted(glob.glob(os.path.join(root, ".agents/agents/*.md"))):
+    txt = open(p).read()
+    m = re.search(r'^name:\s*(\S+)', txt, re.M)
+    if not m or m.group(1) not in agents:
+        continue
+    a = m.group(1)
+    new = resolve_model(model_of(a))
+    new_txt, n = re.subn(r'^model:.*$', f'model: {new}', txt, count=1, flags=re.M)
+    if n and new_txt != txt:
+        open(p, "w").write(new_txt)
+        changed.append(f"md:{a}")
+
+# 2. Project opencode.json — providers + agent models + runnable primaries.
+oc = os.path.join(root, "opencode.json")
+if os.path.exists(oc):
+    d = json.load(open(oc))
+    prov = d.setdefault("provider", {})
+    for name, pspec in providers.items():
+        entry = prov.setdefault(name, {})
+        entry.setdefault("npm", pspec.get("npm", "@ai-sdk/openai-compatible"))
+        entry.setdefault("name", pspec.get("name", name))
+        if pspec.get("base_url"):
+            entry.setdefault("options", {})["baseURL"] = pspec["base_url"]
+        models = entry.setdefault("models", {})
+        for mid in (pspec.get("models") or []):
+            exact = rmap.get(name, {}).get(mid, mid)
+            models.setdefault(exact, {"name": exact})
+        changed.append(f"provider:{name}")
+    ablock = d.setdefault("agent", {})
+    for a in agents:
+        # opencode.json is OpenCode's file: only OpenCode agents belong in it. A
+        # pi (or hermes) agent's model is that harness's id — e.g.
+        # `llamacpp/qwen3.5-9b` — which OpenCode cannot resolve, so writing it
+        # here would hand OpenCode an agent it cannot run. Skip them.
+        if harness_of(a) != "opencode":
+            continue
+        m = resolve_model(model_of(a))
+        # The roster DECLARES every figure it names. Before this, `apply` only
+        # touched an agent already present in opencode.json (`if a in ablock`),
+        # so a figure the roster knew but the config had never seen stayed
+        # undeclared — and OpenCode never loaded it. The roster is the source of
+        # truth; a name in it must reach the harness config.
+        entry = ablock.setdefault(a, {})
+        if entry.get("model") != m:
+            entry["model"] = m; changed.append(f"oc:{a}")
+        if spec_of(a).get("primary"):
+            entry["mode"] = "primary"
+            entry["model"] = m
+            entry.setdefault("description", f"{a} — primary (from config/agents.yaml)")
+            changed.append(f"primary:{a}")
+    with open(oc, "w") as fh:
+        json.dump(d, fh, indent=2); fh.write("\n")
+
+# 3. Cache the resolved combination for get / bin/agent-run.sh.
+os.makedirs(os.path.dirname(resolved_path), exist_ok=True)
+json.dump({a: {"harness": harness_of(a), "model": harness_model(a)}
+           for a in agents}, open(resolved_path, "w"), indent=2)
+
+print(f'agents-config[1]{{action,changed}}:\n  "apply","{",".join(changed) or "none"}"')
+PY

package/bin/apodex-smoke-test.sh

@@ -0,0 +1,105 @@
+#!/usr/bin/env bash
+# apodex-smoke-test — validate an Apodex endpoint (GGUF via llama-router).
+# Serves the model when asked (`--serve`), then runs one tool-calling round
+# and reports pass/fail. Never mutates config; read-only against the seat.
+#
+# Exit codes: 0=pass, 1=fail, 2=unavailable (no weights / no GPU / no server).
+#
+# Usage:
+#   apodex-smoke-test.sh               # probe a running Apodex endpoint
+#   apodex-smoke-test.sh --serve       # serve the GGUF on APODEX_PORT, then test
+#   apodex-smoke-test.sh --port 1234   # override the endpoint port
+#   apodex-smoke-test.sh --model NAME  # override the model id
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+# The operator's settings and secrets live in the home they chose, never in the
+# code tree — a packaged install replaces its tree on upgrade, and a credential
+# must never sit in a tree that ships (Rule 04).
+if [ -z "${YMIR_HOARD_LIB_LOADED:-}" ]; then
+  _yr="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  for _yc in "$_yr/hoard-lib.sh" "$(dirname "$_yr")/bin/hoard-lib.sh"; do
+    [ -r "$_yc" ] && { . "$_yc"; YMIR_HOARD_LIB_LOADED=1; break; }
+  done
+  unset _yr _yc
+fi
+hoard_settings_dir YMIR_SETTINGS_DIR
+hoard_local_env YMIR_ENV_FILE
+
+# Source env if available (project .env.local first, then the private hoard).
+for f in "$YMIR_ENV_FILE" "${YMIR_HOARD:-$HOME/Documents/Ymir}/.env.local"; do
+  [ -f "$f" ] && . "$f" 2>/dev/null || true
+done
+
+PORT="${APODEX_PORT:-1234}"
+BASE="${APODEX_BASE_URL:-http://localhost:$PORT/v1}"
+BASE="${BASE%/}"
+MODEL="${APODEX_MODEL:-apodex-1.0-mini}"
+GGUF="${APODEX_GGUF:-$HOME/Models/FlameF0X/Apodex-1.0-mini-Q4_K_M-GGUF/apodex-1.0-mini-q4_k_m.gguf}"
+SERVE=0
+
+case "${1-}" in
+  --serve) SERVE=1; shift ;;
+  --port) PORT="${2:-$PORT}"; BASE="http://localhost:$PORT/v1"; shift 2 ;;
+  --model) MODEL="${2:-$MODEL}"; shift 2 ;;
+  --help|-h|"") sed -n '2,12p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+esac
+PORT="${APODEX_PORT:-$PORT}"
+
+echo "apodex[smoke]{serve,test,report}:"
+echo "  targeting ${MODEL} @ ${BASE}"
+
+if [ "$SERVE" = 1 ]; then
+  if [ ! -f "$GGUF" ]; then
+    echo "  FAIL: weights not found at $GGUF (set APODEX_GGUF or place the GGUF)"
+    exit 2
+  fi
+  # Check the port is free before raising the server.
+  if command -v lsof >/dev/null 2>&1 && lsof -i ":$PORT" >/dev/null 2>&1; then
+    echo "  FAIL: :${PORT} already occupied — stop the holder or set APODEX_PORT"
+    exit 1
+  fi
+  echo "  serve: llama-server --model $GGUF --port $PORT (background)"
+  llama-server --model "$GGUF" --port "$PORT" --chat-format chatml \
+    --ctx-size 4096 >/dev/null 2>&1 &
+  SERVER_PID=$!
+  echo "  server pid $SERVER_PID"
+  # Wait for the endpoint to answer (bounded).
+  for _ in $(seq 1 30); do
+    curl -fsS --max-time 2 "$BASE/models" >/dev/null 2>&1 && break
+    sleep 1
+  done
+fi
+
+# 1) Endpoint up?
+if ! curl -fsS --max-time 3 "$BASE/models" >/dev/null 2>&1; then
+  echo "  FAIL: no server on ${BASE}"
+  [ "$SERVE" = 1 ] && kill "$SERVER_PID" 2>/dev/null || true
+  exit 1
+fi
+echo "  endpoint: ok"
+
+# 2) Tool-calling round.
+OUT="$(mktemp)"
+trap 'rm -f "$OUT"; [ "${SERVER_PID:-}" ] && kill "$SERVER_PID" 2>/dev/null || true' EXIT
+
+curl -fsS --max-time 60 "$BASE/chat/completions" \
+  -H "Content-Type: application/json" \
+  --data "{\"model\":\"$MODEL\",\"messages\":[{\"role\":\"user\",\"content\":\"What is 2+2?\"}],\"tools\":[{\"type\":\"function\",\"function\":{\"name\":\"add\",\"parameters\":{\"type\":\"object\",\"properties\":{\"a\":{\"type\":\"number\"},\"b\":{\"type\":\"number\"}},\"required\":[\"a\",\"b\"]}}}]}" \
+  > "$OUT" 2>/dev/null
+
+if ! python3 -c "
+import json,sys
+d = json.load(open('$OUT'))
+assert 'choices' in d and d['choices'], 'no choices'
+m = d['choices'][0].get('message', {})
+assert m.get('tool_calls') or m.get('content'), 'no tool_calls/content'
+" 2>/dev/null; then
+  echo "  FAIL: invalid/empty response from ${MODEL}"
+  exit 1
+fi
+
+echo "  PASS: Apodex answered with a valid tool-capable response"
+exit 0

package/bin/bifrost-bridge.sh

@@ -0,0 +1,131 @@
+#!/usr/bin/env bash
+# bifrost-bridge.sh — raise/lower the model bridge (Bifrost: the bridge between
+# realms). Pi's model provider points at a local OpenAI-compatible endpoint;
+# this keeps that endpoint alive so a session never 401s.
+#
+# The provider is the operator's choice (YMIR_MODEL_PROVIDER):
+#   opencode-go        OpenCode Zen Go gateway — needs OPENCODE_GO_API_KEY
+#   lmstudio           LM Studio on localhost — keyless
+#   openai-compatible  any OpenAI-compatible server — optional key
+# No provider is forced to require a key: with no OPENCODE_GO_API_KEY the bridge
+# auto-selects lmstudio so a fresh install with a local model server just works.
+#
+# Usage: bin/bifrost-bridge.sh [--start|--stop|--status] [--port N] [--provider NAME]
+#        bin/bifrost-bridge.sh --version
+set -u
+
+# --- portability shim: bin/ymir-platform.sh --------------------------------
+if [ -z "${YMIR_PLATFORM_LOADED:-}" ]; then
+  for _ymir_c in "$(git rev-parse --show-toplevel 2>/dev/null)/bin/ymir-platform.sh"                  "$(cd "$(dirname "${BASH_SOURCE[0]}")/.." 2>/dev/null && pwd)/bin/ymir-platform.sh"; do
+    [ -n "$_ymir_c" ] && [ -r "$_ymir_c" ] && { . "$_ymir_c"; YMIR_PLATFORM_LOADED=1; break; }
+  done
+  unset _ymir_c
+fi
+
+VERSION="2.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+# The operator's settings and secrets live in the home they chose, never in the
+# code tree — a packaged install replaces its tree on upgrade, and a credential
+# must never sit in a tree that ships (Rule 04).
+if [ -z "${YMIR_HOARD_LIB_LOADED:-}" ]; then
+  _yr="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  for _yc in "$_yr/hoard-lib.sh" "$(dirname "$_yr")/bin/hoard-lib.sh"; do
+    [ -r "$_yc" ] && { . "$_yc"; YMIR_HOARD_LIB_LOADED=1; break; }
+  done
+  unset _yr _yc
+fi
+hoard_settings_dir YMIR_SETTINGS_DIR
+hoard_local_env YMIR_ENV_FILE
+hoard_state_dir YMIR_STATE_DIR
+hoard_data_dir YMIR_DATA_DIR
+
+# The roots that live OUTSIDE the code tree: this machine's records and the
+# runtime state belong to the home the operator chose at installation, never in
+# the tree — a packaged install replaces its tree on upgrade (Rule 04).
+BRIDGE="$ROOT/.agents/backend/model-bridge.py"
+ENV_FILE="${BROKK_ENV_FILE:-$YMIR_ENV_FILE}"
+PORT="${OPENCODE_GO_BRIDGE_PORT:-4603}"
+PID_FILE="$YMIR_STATE_DIR/model-bridge.pid"
+LOG_FILE="$YMIR_STATE_DIR/model-bridge.log"
+PROVIDER="${YMIR_MODEL_PROVIDER:-}"
+
+case "${1-}" in
+  -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;;
+  -h|--help) sed -n '2,15p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+esac
+ACTION="start"
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --start|"") ACTION=start; shift ;;
+    --stop|stop) ACTION=stop; shift ;;
+    --status|status) ACTION=status; shift ;;
+    --port) PORT=${2-}; shift 2 ;;
+    --provider) PROVIDER=${2-}; shift 2 ;;
+    *) printf 'error: unknown flag %s\nhelp: bin/bifrost-bridge.sh [--start|--stop|--status|--port|--provider]\n' "$1" >&2; exit 2 ;;
+  esac
+done
+
+listening() { (exec 3<>"/dev/tcp/127.0.0.1/$PORT") 2>/dev/null && return 0 || return 1; }
+
+# Read a key from the env file without sourcing it.
+env_value() {
+  local name="$1"
+  [ -r "$ENV_FILE" ] || return 1
+  sed -nE "s/^[[:space:]]*${name}[[:space:]]*=[[:space:]]*(.*)$/\1/p" "$ENV_FILE" \
+    | tail -1 | sed -E 's/^"(.*)"$/\1/; s/^'"'"'(.*)'"'"'$/\1/'
+}
+
+case "$ACTION" in
+  status)
+    if listening; then
+      printf 'bridge[1]{port,status,provider}:\n  %s,"up","%s"\n' "$PORT" "${PROVIDER:-auto}"
+    else
+      printf 'bridge[1]{port,status,provider}:\n  %s,"down","%s"\n' "$PORT" "${PROVIDER:-auto}"
+    fi
+    exit 0 ;;
+  stop)
+    stopped=0
+    if [ -r "$PID_FILE" ]; then pid=$(tr -d '[:space:]' <"$PID_FILE"); if kill "$pid" 2>/dev/null; then stopped=1; fi; rm -f "$PID_FILE"; fi
+    if listening; then ymir_kill_matching "model-bridge.py" 2>/dev/null && stopped=1; fi
+    if [ "$stopped" = 1 ]; then printf 'bridge: stopped\n'; else printf 'bridge: already stopped\n'; fi
+    exit 0 ;;
+esac
+
+if listening; then
+  pgrep -f "model-bridge.py" >"$PID_FILE" 2>/dev/null || true
+  printf 'bridge[1]{port,status}:\n  %s,"already up"\n' "$PORT"
+  exit 0
+fi
+[ -e "$BRIDGE" ] || { printf 'error: bridge script not found: %s\nhelp: expected .agents/backend/model-bridge.py\n' "$BRIDGE"; exit 1; }
+
+# Choose the provider when the operator did not pin one. Prefer an explicitly
+# configured provider; otherwise use opencode-go only when a key actually
+# exists, and fall back to the keyless local provider so install "just works".
+if [ -z "$PROVIDER" ]; then
+  if [ -n "$(env_value YMIR_MODEL_PROVIDER)" ]; then
+    PROVIDER="$(env_value YMIR_MODEL_PROVIDER)"
+  elif [ -n "$(env_value OPENCODE_GO_API_KEY)" ] || [ -n "${OPENCODE_GO_API_KEY:-}" ]; then
+    PROVIDER="opencode-go"
+  else
+    PROVIDER="lmstudio"
+  fi
+fi
+
+# A missing env file is fine for keyless providers; the bridge reads what it can.
+mkdir -p "$YMIR_STATE_DIR"
+nohup python3 "$BRIDGE" --port "$PORT" --env "$ENV_FILE" --provider "$PROVIDER" >"$LOG_FILE" 2>&1 &
+echo $! >"$PID_FILE"
+sleep 2
+if listening; then
+  printf 'bridge[1]{port,status,provider}:\n  %s,"started","%s"\n' "$PORT" "$PROVIDER"
+else
+  printf 'error: bridge failed to start (provider=%s); see %s\n' "$PROVIDER" "${LOG_FILE#"$ROOT"/}" >&2
+  case "$PROVIDER" in
+    opencode-go) printf 'help: set OPENCODE_GO_API_KEY in %s, or run with --provider lmstudio\n' "${ENV_FILE#"$ROOT"/}" >&2 ;;
+    lmstudio)    printf 'help: is LM Studio running and serving on 127.0.0.1:1234? Or set YMIR_MODEL_PROVIDER=opencode-go\n' >&2 ;;
+    *)           printf 'help: check YMIR_MODEL_BASE_URL and the provider in %s\n' "${ENV_FILE#"$ROOT"/}" >&2 ;;
+  esac
+  exit 1
+fi

package/bin/bifrost-ingress.sh

@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+# bifrost-ingress.sh — raise/lower the ingress stack (Bifrost · Heimdall · Gjallarhorn).
+#
+# Config lives in `midgard/infrastructure/ingress/`. This dispatches to the owning
+# engines when present (Caddy for Bifrost, oauth2-proxy for Heimdall, cloudflared
+# for Gjallarhorn) and reports honestly when a binary is missing. Galdr TOON.
+#
+# Usage: bin/bifrost-ingress.sh [start|stop|status|validate]
+#        bin/bifrost-ingress.sh --version
+set -u
+
+# --- portability shim: bin/ymir-platform.sh --------------------------------
+if [ -z "${YMIR_PLATFORM_LOADED:-}" ]; then
+  for _ymir_c in "$(git rev-parse --show-toplevel 2>/dev/null)/bin/ymir-platform.sh"                  "$(cd "$(dirname "${BASH_SOURCE[0]}")/.." 2>/dev/null && pwd)/bin/ymir-platform.sh"; do
+    [ -n "$_ymir_c" ] && [ -r "$_ymir_c" ] && { . "$_ymir_c"; YMIR_PLATFORM_LOADED=1; break; }
+  done
+  unset _ymir_c
+fi
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+ING="$ROOT/midgard/infrastructure/ingress"
+
+case "${1-}" in
+  -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;;
+  -h|--help|"") sed -n '2,10p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+esac
+ACTION="${1:-status}"
+
+has() { command -v "$1" >/dev/null 2>&1; }
+port_up() { (exec 3<>"/dev/tcp/127.0.0.1/$1") 2>/dev/null; }
+
+case "$ACTION" in
+  validate)
+    rc=0
+    if has caddy; then
+      caddy validate --config "$ING/Caddyfile" >/dev/null 2>&1 && printf '  "Bifrost","valid"\n' || { printf '  "Bifrost","INVALID"\n'; rc=1; }
+    else printf '  "Bifrost","caddy not installed"\n'; fi
+    printf 'config[3]{asset,path,status}:\n'
+    printf '  "Bifrost","%s","%s"\n' "${ING#"$ROOT"/}/Caddyfile" "$([ -f "$ING/Caddyfile" ] && echo present || echo missing)"
+    printf '  "Heimdall","%s","%s"\n' "${ING#"$ROOT"/}/oauth2-proxy.cfg" "$([ -f "$ING/oauth2-proxy.cfg" ] && echo present || echo missing)"
+    printf '  "Gjallarhorn","%s","%s"\n' "${ING#"$ROOT"/}/cloudflared.yml" "$([ -f "$ING/cloudflared.yml" ] && echo present || echo missing)"
+    exit $rc
+    ;;
+
+  status)
+    printf 'ingress[3]{edge,engine,status}:'
+    printf '\n'
+    if port_up 80 || port_up 443; then printf '  "Bifrost","caddy","listening"\n'; else printf '  "Bifrost","caddy","%s"\n' "$(has caddy && echo present || echo not-installed)"; fi
+    if port_up 4180; then printf '  "Heimdall","oauth2-proxy","listening"\n'; else printf '  "Heimdall","oauth2-proxy","%s"\n' "$(has oauth2-proxy && echo present || echo not-installed)"; fi
+    if has cloudflared; then printf '  "Gjallarhorn","cloudflared","present"\n'; else printf '  "Gjallarhorn","cloudflared","not-installed"\n'; fi
+    ;;
+
+  start)
+    ok=0
+    if [ -f "$ING/Caddyfile" ] && has caddy; then
+      caddy start --config "$ING/Caddyfile" >/dev/null 2>&1 && { printf 'Bifrost: raised\n'; ok=1; } || printf 'Bifrost: failed to raise\n' >&2
+    else printf 'Bifrost: skipped (%s)\n' "$(has caddy && echo config-missing || echo 'caddy not installed')" >&2; fi
+    if [ -f "$ING/oauth2-proxy.cfg" ] && has oauth2-proxy; then
+      nohup oauth2-proxy --config "$ING/oauth2-proxy.cfg" >/dev/null 2>&1 & printf 'Heimdall: raised\n'; ok=1
+    else printf 'Heimdall: skipped (%s)\n' "$(has oauth2-proxy && echo config-missing || echo 'oauth2-proxy not installed')" >&2; fi
+    if [ -f "$ING/cloudflared.yml" ] && has cloudflared; then
+      nohup cloudflared tunnel --config "$ING/cloudflared.yml" run >/dev/null 2>&1 & printf 'Gjallarhorn: raised\n'; ok=1
+    else printf 'Gjallarhorn: skipped (%s)\n' "$(has cloudflared && echo config-missing || echo 'cloudflared not installed')" >&2; fi
+    [ "$ok" = 1 ] || { printf 'error: no ingress engine could start\nhelp: install caddy / oauth2-proxy / cloudflared, then re-run\n' >&2; exit 1; }
+    ;;
+
+  stop)
+    has caddy && caddy stop >/dev/null 2>&1 && echo "Bifrost: lowered"
+    ymir_kill_matching 'oauth2-proxy --config' >/dev/null 2>&1 && echo "Heimdall: lowered"
+    ymir_kill_matching 'cloudflared tunnel' >/dev/null 2>&1 && echo "Gjallarhorn: lowered"
+    printf 'ingress: down\n'
+    ;;
+
+  *) printf 'error: unknown action %s\nhelp: bin/bifrost-ingress.sh [start|stop|status|validate]\n' "$ACTION" >&2; exit 2 ;;
+esac