@zerwiz/ymir 0.1.4 → 0.1.5

package/bin/mimir-ingest.sh

@@ -0,0 +1,131 @@
+#!/usr/bin/env bash
+# mimir-ingest.sh — ingest the repo's data material into the well (Mimirsbrunn).
+#
+# Mímir drinks from the operator's business material — the hoard's
+# `docs/business/` (moved there from `assets/data/` by the hoard migration):
+# each Markdown section becomes an episode with
+# a content hash, tags, source, and timestamp. Episodes are appended to the local
+# well store (`.agents/memory/well/episodes.jsonl`) and POSTed to the engram
+# bridge (`MIMIRSBRUNN_URL`, default http://127.0.0.1:4602/observe) when it is
+# reachable. Idempotent by content hash. Galdr-style: TOON out, structured errors.
+#
+# Usage: bin/mimir-ingest.sh [--dry-run] [--path <file-or-dir>] [--quiet]
+#        bin/mimir-ingest.sh --version
+set -u
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+# shellcheck source=bin/hoard-lib.sh
+. "$SCRIPT_DIR/hoard-lib.sh"
+hoard_root HOARD
+# The business material lives in the hoard (private, untracked). Keep the old
+# location as a fallback so a pre-migration home still works.
+DATA="${BROKK_DATA_SOURCE:-$HOARD/docs/business}"
+[ -e "$DATA" ] || DATA="$ROOT/assets/data"
+STORE_DIR="$ROOT/.agents/memory/well"
+STORE="$STORE_DIR/episodes.jsonl"
+BRIDGE="${MIMIRSBRUNN_URL:-http://127.0.0.1:4602}"
+
+DRY=0; QUIET=0; SRC="$DATA"
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;;
+    -h|--help) sed -n '2,14p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    --dry-run) DRY=1; shift ;;
+    --quiet) QUIET=1; shift ;;
+    --path) SRC=${2-}; shift 2 ;;
+    *) printf 'error: unknown flag %s\nhelp: bin/mimir-ingest.sh [--dry-run|--path <p>|--quiet]\n' "$1" >&2; exit 2 ;;
+  esac
+done
+
+[ -e "$SRC" ] || { printf 'error: data path not found: %s\nhelp: pass --path, or put material in \$YMIR_HOARD/docs/business/\n' "$SRC"; exit 1; }
+
+mkdir -p "$STORE_DIR"
+[ -e "$STORE" ] || : >"$STORE"
+
+# Load every hash already in the store once, so dedupe is O(1) per section
+# instead of rescanning the whole store for each chunk (O(chunks x store)).
+declare -A SEEN_HASH
+while IFS= read -r _h; do [ -n "$_h" ] && SEEN_HASH["$_h"]=1; done < <(
+  grep -o '"hash":"[^"]*"' "$STORE" 2>/dev/null | cut -d'"' -f4
+)
+
+have_bridge=0
+if command -v curl >/dev/null 2>&1 && curl -fsS --max-time 2 "$BRIDGE/health" >/dev/null 2>&1; then
+  have_bridge=1
+fi
+
+declare -a FILE N ADD SKIP
+total_add=0; total_skip=0; files=0
+
+ingest_file() {
+  local file=$1 rel chunks=0 added=0 skipped=0 heading="" para="" line
+  rel="${file#"$ROOT"/}"
+  while IFS= read -r line; do
+    case "$line" in
+      \#*)
+        if [ -n "$heading" ] || [ -n "$para" ]; then
+          content=$(printf '%s\n\n%s' "$heading" "$para" | sed -e 's/[[:space:]]*$//')
+          if [ -n "$para" ]; then
+            hash=$(printf '%s' "$content" | sha256sum | cut -d' ' -f1)
+            if [ -n "${SEEN_HASH[$hash]:-}" ]; then
+              skipped=$((skipped + 1))
+            else
+              SEEN_HASH[$hash]=1
+              added=$((added + 1))
+              if [ "$DRY" = 0 ]; then
+                ts=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+                json=$(printf '{"timestamp":"%s","source":"%s","tags":["data"],"content":%s,"hash":"%s"}' \
+                  "$ts" "$rel" "$(printf '%s' "$content" | python3 -c 'import json,sys;print(json.dumps(sys.stdin.read()))')" "$hash")
+                printf '%s\n' "$json" >>"$STORE"
+                if [ "$have_bridge" = 1 ]; then
+                  curl -fsS --max-time 3 -X POST -H 'content-type: application/json' \
+                    -d "$json" "$BRIDGE/observe" >/dev/null 2>&1 || true
+                fi
+              fi
+            fi
+          fi
+          chunks=$((chunks + 1))
+        fi
+        heading="$line"
+        para=""
+        ;;
+      *) para="${para:+$para$'\n'}$line" ;;
+    esac
+  done <"$file"
+  # trailing section
+  if [ -n "$para" ]; then
+    content=$(printf '%s\n\n%s' "$heading" "$para" | sed -e 's/[[:space:]]*$//')
+    hash=$(printf '%s' "$content" | sha256sum | cut -d' ' -f1)
+    if [ -n "${SEEN_HASH[$hash]:-}" ]; then skipped=$((skipped + 1)); else
+      SEEN_HASH[$hash]=1
+      added=$((added + 1))
+      if [ "$DRY" = 0 ]; then
+        ts=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+        json=$(printf '{"timestamp":"%s","source":"%s","tags":["data"],"content":%s,"hash":"%s"}' \
+          "$ts" "$rel" "$(printf '%s' "$content" | python3 -c 'import json,sys;print(json.dumps(sys.stdin.read()))')" "$hash")
+        printf '%s\n' "$json" >>"$STORE"
+        [ "$have_bridge" = 1 ] && curl -fsS --max-time 3 -X POST -H 'content-type: application/json' -d "$json" "$BRIDGE/observe" >/dev/null 2>&1 || true
+      fi
+    fi
+    chunks=$((chunks + 1))
+  fi
+  FILE+=("$rel"); N+=("$chunks"); ADD+=("$added"); SKIP+=("$skipped")
+  total_add=$((total_add + added)); total_skip=$((total_skip + skipped)); files=$((files + 1))
+}
+
+if [ -d "$SRC" ]; then
+  while IFS= read -r f; do ingest_file "$f"; done < <(find "$SRC" -name '*.md' | sort)
+else
+  ingest_file "$SRC"
+fi
+
+if [ "$QUIET" = 0 ]; then
+  printf 'mimir_ingest[%s]{source,sections,added,skipped}:\n' "${#FILE[@]}"
+  for i in "${!FILE[@]}"; do
+    printf '  "%s",%s,%s,%s\n' "${FILE[$i]}" "${N[$i]}" "${ADD[$i]}" "${SKIP[$i]}"
+  done
+fi
+printf 'well: store=%s entries=%s bridge=%s\n' "${STORE#"$ROOT"/}" "$(wc -l <"$STORE" | tr -d ' ')" "$([ "$have_bridge" = 1 ] && echo online || echo offline)"
+printf 'help[1]: query the well with `bin/rodd-operational-input.sh` kinds / the Mimirsbrunn bridge\n'

package/bin/mimir.sh

@@ -0,0 +1,113 @@
+#!/usr/bin/env bash
+# mimir.sh — the well (Mimirsbrunn). Drink before you act, water it after.
+#
+# Talks to Kaia's engram bridge (:4602) when it is up; otherwise operates the
+# local well store (`.agents/memory/well/episodes.jsonl`). Galdr-style TOON.
+#
+# Usage:
+#   mimir.sh health
+#   mimir.sh recall <query> [--k N] [--mode hybrid|cosine|spreading]
+#   mimir.sh observe <text> [--tags a,b] [--source S]
+#   mimir.sh timeline [--entity X]
+#   mimir.sh --version
+set -u
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+YMIR_HOME="${YMIR_HOME:-$HOME/Documents/Ymir}"
+WELL="${YMIR_MEMORY_DIR:-$YMIR_HOME/memory/well}/episodes.jsonl"
+BRIDGE="${MIMIRSBRUNN_URL:-http://127.0.0.1:4602}"
+
+usage() { sed -n '2,12p' "$0" | sed 's/^# \{0,1\}//'; }
+
+CMD="${1-}"; shift || true
+case "$CMD" in
+  -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;;
+  -h|--help|"") usage; exit 0 ;;
+esac
+[ -e "$WELL" ] || : >"$WELL"
+
+bridge_up() { command -v curl >/dev/null 2>&1 && curl -fsS --max-time 2 "$BRIDGE/health" >/dev/null 2>&1; }
+well_count() { wc -l <"$WELL" | tr -d ' '; }
+
+case "$CMD" in
+  health)
+    if bridge_up; then
+      printf 'well[1]{state,entries,bridge}:\n  "WARM",%s,"online"\n' "$(well_count)"
+    else
+      printf 'well[1]{state,entries,bridge}:\n  "COLD",%s,"offline"\n' "$(well_count)"
+    fi
+    ;;
+
+  recall)
+    Q="${1-}"; shift || true
+    K=5; MODE=hybrid
+    while [ $# -gt 0 ]; do case "$1" in --k) K=${2-5}; shift 2 ;; --mode) MODE=${2-hybrid}; shift 2 ;; *) shift ;; esac; done
+    [ -n "$Q" ] || { printf 'error: recall needs a query\nhelp: bin/mimir.sh recall "<query>"\n' >&2; exit 2; }
+    if bridge_up; then
+      out=$(curl -fsS --max-time 5 "$BRIDGE/recall?q=$(printf '%s' "$Q" | python3 -c 'import sys,urllib.parse;print(urllib.parse.quote(sys.stdin.read()))')&k=$K&mode=$MODE" 2>/dev/null)
+      [ -n "$out" ] && { printf '%s\n' "$out" | python3 -c 'import json,sys
+d=json.load(sys.stdin)
+rs=d.get("results",d if isinstance(d,list) else [])
+print(f"recall[{len(rs)}]{{score,source,title}}:")
+for r in rs[:20]:
+    e=r.get("episode",r); sc=r.get("score",0)
+    t=(e.get("content","").split("\n")[0] or "")[:90]
+    print(f"  {sc},{(e.get(\"agents\") or [\"well\"])[0]},{t}")' 2>/dev/null && exit 0; }
+    fi
+    # local fallback: substring search over the well
+    python3 - "$WELL" "$Q" "$K" <<'PY'
+import json,sys
+well,q,k=sys.argv[1],sys.argv[2].lower(),int(sys.argv[3])
+rows=[]
+for line in open(well, encoding='utf-8', errors='ignore'):
+    if not line.strip().startswith('{'): continue
+    try: e=json.loads(line)
+    except: continue
+    c=e.get('content','')
+    if q in c.lower(): rows.append((e,c))
+print(f"recall[{min(len(rows),k)}]{{score,source,title}}:")
+for e,c in rows[-k:][::-1]:
+    t=(c.split('\n')[0] or '').replace('#','').strip()[:90]
+    print(f"  0.5,\"{e.get('source','well')}\",\"{t}\"")
+PY
+    ;;
+
+  observe)
+    TEXT="${1-}"; shift || true
+    TAGS="runtime"; SRC="brokk"
+    while [ $# -gt 0 ]; do case "$1" in --tags) TAGS=${2-}; shift 2 ;; --source) SRC=${2-}; shift 2 ;; *) shift ;; esac; done
+    [ -n "$TEXT" ] || { printf 'error: observe needs text\nhelp: bin/mimir.sh observe "<text>"\n' >&2; exit 2; }
+    json=$(printf '%s' "$TEXT" | python3 -c 'import json,sys,hashlib,datetime
+t=sys.stdin.read()
+print(json.dumps({"timestamp":datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),"source":"'"$SRC"'","tags":"'"$TAGS"'".split(","),"content":t,"hash":hashlib.sha256(t.encode()).hexdigest()}))')
+    printf '%s\n' "$json" >>"$WELL"
+    if bridge_up; then curl -fsS --max-time 3 -X POST -H 'content-type: application/json' -d "$json" "$BRIDGE/observe" >/dev/null 2>&1 || true; fi
+    printf 'observed[1]{source,tags,bridge}:\n  "%s","%s","%s"\n' "$SRC" "$TAGS" "$(bridge_up && echo online || echo local)"
+    ;;
+
+  timeline)
+    ENTITY=""; while [ $# -gt 0 ]; do case "$1" in --entity) ENTITY=${2-}; shift 2 ;; *) shift ;; esac; done
+    if bridge_up && [ -n "$ENTITY" ]; then
+      curl -fsS --max-time 5 "$BRIDGE/timeline?entity=$(printf '%s' "$ENTITY" | python3 -c 'import sys,urllib.parse;print(urllib.parse.quote(sys.stdin.read()))')" 2>/dev/null && exit 0
+    fi
+    python3 - "$WELL" <<'PY'
+import json,sys
+rows=[]
+for line in open(sys.argv[1], encoding='utf-8', errors='ignore'):
+    if not line.strip().startswith('{'): continue
+    try: e=json.loads(line)
+    except: continue
+    rows.append(e)
+print(f"timeline[{min(len(rows),20)}]{{ts,source,title}}:")
+for e in rows[-20:][::-1]:
+    t=(e.get('content','').split('\n')[0] or '').replace('#','').strip()[:80]
+    print(f"  \"{e.get('timestamp','')}\",\"{e.get('source','well')}\",\"{t}\"")
+PY
+    ;;
+
+  *)
+    printf 'error: unknown command %s\nhelp: bin/mimir.sh [health|recall|observe|timeline|--version]\n' "$CMD" >&2
+    exit 2 ;;
+esac

package/bin/mjollnir-webhook.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+# mjollnir-webhook.sh — HMAC-verified GitHub webhook → Mjollnir (W0018).
+#
+# Verifies the X-Hub-Signature-256 HMAC of the raw body against GITHUB_WEBHOOK_SECRET
+# (from `.env.local`), and on an `issues`/`opened` event dispatches `mjollnir run`.
+# An unverified webhook is refused — DATA ONLY, never a command. Galdr-style TOON.
+#
+# Usage: mjollnir-webhook.sh [--repo <dir>] [--no-spawn]  < payload.json
+#        mjollnir-webhook.sh --version
+# Header: X-Hub-Signature-256: sha256=<hex>, X-GitHub-Event: <event>
+set -u
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+ENV_FILE="${BROKK_ENV_FILE:-$ROOT/.env.local}"
+
+case "${1-}" in
+  -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;;
+  -h|--help|"") sed -n '2,11p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+esac
+
+REPO=""; NOSPAWN=0
+while [ $# -gt 0 ]; do case "$1" in --repo) REPO=${2-}; shift 2 ;; --no-spawn) NOSPAWN=1; shift ;; *) shift ;; esac; done
+
+SIG="${HTTP_X_HUB_SIGNATURE_256:-}"
+EVENT="${HTTP_X_GITHUB_EVENT:-}"
+[ -n "$SIG" ] || { printf 'error: missing X-Hub-Signature-256 (did Bifrost forward headers?)\n' >&2; exit 401; }
+[ -r "$ENV_FILE" ] || { printf 'error: env file not found: %s\n' "$ENV_FILE" >&2; exit 1; }
+SECRET=$(grep -E '^GITHUB_WEBHOOK_SECRET=' "$ENV_FILE" | head -1 | cut -d= -f2-)
+[ -n "$SECRET" ] || { printf 'error: GITHUB_WEBHOOK_SECRET unset in .env.local\n' >&2; exit 401; }
+
+BODY=$(cat)
+VERDICT=$(SECRET="$SECRET" SIG="$SIG" BODY="$BODY" python3 -c '
+import os,hmac,hashlib
+secret=os.environ["SECRET"].encode(); body=os.environ["BODY"].encode()
+sig=os.environ["SIG"].strip(); want="sha256="+hmac.new(secret,body,hashlib.sha256).hexdigest()
+print("valid" if hmac.compare_digest(sig,want) else "invalid")')
+if [ "$VERDICT" != valid ]; then
+  printf 'webhook[1]{signature,status}:\n  "invalid","refused"\n' >&2
+  exit 401
+fi
+printf 'webhook[1]{signature,event,status}:\n  "valid","%s","accepted"\n' "${EVENT:-unknown}"
+
+[ "$EVENT" = issues ] || { printf 'help[1]: event %s is not handled\n' "${EVENT:-unknown}"; exit 0; }
+ACTION=$(BODY="$BODY" python3 -c 'import os,json
+try: d=json.loads(os.environ["BODY"])
+except: d={}
+print(d.get("action",""))')
+NUMBER=$(BODY="$BODY" python3 -c 'import os,json
+try: d=json.loads(os.environ["BODY"])
+except: d={}
+print((d.get("issue") or {}).get("number",""))')
+[ "$ACTION" = opened ] && [ -n "$NUMBER" ] || { printf 'help[1]: issues/%s ignored\n' "$ACTION"; exit 0; }
+
+ARGS=(run --issue "$NUMBER" --mode direct-PR)
+[ -n "$REPO" ] && ARGS+=(--repo "$REPO")
+[ "$NOSPAWN" = 1 ] && ARGS+=(--no-spawn)
+exec "$SCRIPT_DIR/mjollnir.sh" "${ARGS[@]}"

package/bin/mjollnir.sh

@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+# mjollnir.sh — the hammer (W0018). An issue becomes a PR: read the issue, cut a
+# Yggdrasil worktree, spawn an Eindri (Utgard-sealed), run tests, open a PR, and
+# hand it to Glitnir for human review. Never force-merges. Galdr-style TOON.
+#
+# Usage:
+#   mjollnir.sh run --repo <dir> --issue <n> [--mode direct-PR|no-mistakes|local-only]
+#                  [--harness <h>] [--isolation auto|on|off] [--no-spawn]
+#   mjollnir.sh status
+#   mjollnir.sh --version
+set -u
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+ENV_FILE="${BROKK_ENV_FILE:-$ROOT/.env.local}"
+
+usage() { sed -n '2,13p' "$0" | sed 's/^# \{0,1\}//'; }
+CMD="${1-}"; shift || true
+case "$CMD" in
+  -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;;
+  -h|--help|"") usage; exit 0 ;;
+esac
+
+REPO=""; ISSUE=""; MODE=direct-PR; HARNESS=""; ISO=auto; NOSPAWN=0; TITLE=""; BODY=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --repo) REPO=${2-}; shift 2 ;;
+    --issue) ISSUE=${2-}; shift 2 ;;
+    --mode) MODE=${2-direct-PR}; shift 2 ;;
+    --harness) HARNESS=${2-}; shift 2 ;;
+    --isolation) ISO=${2-auto}; shift 2 ;;
+    --no-spawn) NOSPAWN=1; shift ;;
+    --title) TITLE=${2-}; shift 2 ;;
+    --body) BODY=${2-}; shift 2 ;;
+    *) shift ;;
+  esac
+done
+
+if [ "$CMD" = status ]; then
+  printf 'mjollnir[2]{field,value}:\n'
+  printf '  "repo","%s"\n' "${REPO:-$ROOT}"
+  printf '  "pending","%s"\n' "$(find "$ROOT/data" -maxdepth 2 -name 'brief.md' -path '*issue-*' 2>/dev/null | wc -l | tr -d ' ')"
+  exit 0
+fi
+[ "$CMD" = run ] || { printf 'error: unknown command %s\nhelp: bin/mjollnir.sh [run|status|--version]\n' "$CMD" >&2; exit 2; }
+[ -n "$ISSUE" ] || { printf 'error: run needs --issue <n>\n' >&2; exit 2; }
+
+# The `no-mistakes` posture runs through the OSS clean-PR gate engine.
+if [ "$MODE" = "no-mistakes" ]; then
+  command -v no-mistakes >/dev/null 2>&1 || { printf 'error: no-mistakes engine not installed\nhelp: bin/ymir-install.sh (github.com/kunchenguid/no-mistakes)\n' >&2; exit 1; }
+  [ -f "$ROOT/.no-mistakes.yaml" ] || printf 'warn: .no-mistakes.yaml absent — the gate uses defaults\n' >&2
+fi
+[ -n "$REPO" ] || { printf 'error: run needs --repo <dir>\n' >&2; exit 2; }
+[ -d "$REPO" ] || { printf 'error: repo not found: %s\n' "$REPO" >&2; exit 1; }
+
+# 1. Read the issue (GitHub) unless title/body were supplied.
+if [ -z "$TITLE" ] && command -v gh >/dev/null 2>&1 && gh auth status >/dev/null 2>&1; then
+  json=$(gh issue view "$ISSUE" --json title,body,url -R "$(git -C "$REPO" remote get-url origin 2>/dev/null || echo .)" 2>/dev/null) || json=""
+  if [ -n "$json" ]; then
+    TITLE=$(printf '%s' "$json" | python3 -c 'import json,sys;print(json.load(sys.stdin).get("title",""))')
+    BODY=$(printf '%s' "$json" | python3 -c 'import json,sys;print(json.load(sys.stdin).get("body",""))')
+  fi
+fi
+[ -n "$TITLE" ] || { printf 'error: could not read issue %s (gh unauth? pass --title/--body)\n' "$ISSUE" >&2; exit 1; }
+
+ID="issue-$ISSUE"
+printf 'mjollnir[1]{issue,task,mode,repo}:\n  "%s","%s","%s","%s"\n' "$ISSUE" "$ID" "$MODE" "$REPO"
+
+# 2. Scaffold the brief (the worker's contract).
+"$SCRIPT_DIR/erindi-brief.sh" "$ID" "$(basename "$REPO")" --mode "$MODE" >/dev/null 2>&1 || true
+BRIEF="$ROOT/data/$ID/brief.md"
+if [ -f "$BRIEF" ]; then
+  { printf '\n\n## Issue #%s — %s\n\n%s\n' "$ISSUE" "$TITLE" "$BODY"; } >>"$BRIEF"
+fi
+
+# 3. Spawn the Eindri (or stop for --no-spawn).
+if [ "$NOSPAWN" = 1 ]; then
+  printf 'spawned[1]{task,status}:\n  "%s","brief-ready (no-spawn)"\n' "$ID"
+  exit 0
+fi
+ARGS=(agent spawn "$ID" "$REPO" --mode "$MODE" --isolation "$ISO")
+[ -n "$HARNESS" ] && ARGS+=(--harness "$HARNESS")
+"$SCRIPT_DIR/brokk" "${ARGS[@]}"
+printf 'help[1]: the worker opens the PR; Glitnir reviews — Mjollnir never force-merges\n'

package/bin/model-hardware.sh

@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+# model-hardware.sh — profile THIS machine for local models and record the
+# baseline in data/local-models.md.
+#
+# Local models are hardware-bound, so the install learns the machine before it
+# advises: GPU + VRAM, CPU, RAM. It states the baseline (llama.cpp — llama-server
+# / llama-swap — is fastest on the GPU; coding wants >= 80000 context) and, when
+# online, marks the settings section for Brokk to research the exact best
+# settings for this GPU and write them here.
+#
+# Usage:
+#   model-hardware.sh            # detect + write data/local-models.md
+#   model-hardware.sh --print    # detect + print, do not write
+#   model-hardware.sh --version
+set -u
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+OUT="${YMIR_LOCAL_MODELS_DOC:-$ROOT/data/local-models.md}"
+PRINT_ONLY=0
+
+case "${1-}" in -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;; -h|--help) sed -n '2,14p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;; esac
+[ "${1-}" = "--print" ] && PRINT_ONLY=1
+
+have() { command -v "$1" >/dev/null 2>&1; }
+
+gpu="$(nvidia-smi --query-gpu=name,memory.total --format=csv,noheader 2>/dev/null | head -1 || true)"
+[ -n "$gpu" ] || gpu="$( (lspci 2>/dev/null || true) | grep -iE 'vga|3d|display' | head -1 | sed 's/^[0-9a-f:.]* //' || true)"
+[ -n "$gpu" ] || gpu="none detected"
+cpu="$( (grep -m1 'model name' /proc/cpuinfo 2>/dev/null || sysctl -n machdep.cpu.brand_string 2>/dev/null || true) | sed 's/^.*: //' )"
+[ -n "$cpu" ] || cpu="unknown"
+ram="$( (free -h 2>/dev/null | awk '/Mem:/{print $2}') || true )"
+[ -n "$ram" ] || ram="unknown"
+
+online=no
+if curl -fsS --max-time 4 -o /dev/null https://github.com 2>/dev/null; then online=yes; fi
+
+printf 'model-hardware[1]{gpu,cpu,ram,online}:\n  "%s","%s","%s","%s"\n' "$gpu" "$cpu" "$ram" "$online"
+
+if [ "$PRINT_ONLY" = 1 ]; then exit 0; fi
+
+mkdir -p "$(dirname "$OUT")"
+# Idempotent block: replace whatever sits between the markers.
+block="<!-- model-hardware:begin -->
+## This machine
+- **GPU:** ${gpu}
+- **CPU:** ${cpu}
+- **RAM:** ${ram}
+
+## The baseline
+- **llama.cpp** (llama-server / llama-swap) is the fastest local engine on the GPU —
+  build/run the CUDA build; keep K and V the same KV type (q8_0).
+- **Coding wants >= 80000 context.** Measure the real ceiling: load more until a
+  request OOMs, then drop one step (ctx is per-model).
+- **Bench to the maximum:** load the \`.agents/skills/modeltesting\` skill, then
+  \`bin/models-detect.sh --write\` to register what serves.
+<!-- model-hardware:end -->"
+
+# The researched settings are NOT in the managed block, so a re-run never clobbers
+# them. Brokk fills them once, online, for this GPU.
+settings_section="## Best settings for THIS hardware (researched)
+<!-- Brokk: search the web for 'llama.cpp best settings <this GPU>' and record the
+     exact flags (--fit / --n-gpu-layers / --n-cpu-moe / --ctx-size / kv / -fa). -->"
+
+if [ -f "$OUT" ] && grep -q "model-hardware:begin" "$OUT"; then
+  python3 - "$OUT" "$block" <<'PY'
+import sys
+path, block = sys.argv[1], sys.argv[2]
+t = open(path).read()
+a = t.index("<!-- model-hardware:begin -->")
+b = t.index("<!-- model-hardware:end -->") + len("<!-- model-hardware:end -->")
+open(path, "w").write(t[:a] + block + t[b:])
+PY
+else
+  { [ -f "$OUT" ] && cat "$OUT" || printf '# Local models\n\n'; printf '\n%s\n' "$block"; } >"$OUT.tmp" && mv "$OUT.tmp" "$OUT"
+fi
+# The (researched) settings section is created once and never overwritten.
+if ! grep -q "## Best settings for THIS hardware" "$OUT" 2>/dev/null; then
+  printf '\n%s\n' "$settings_section" >>"$OUT"
+fi
+printf 'model-hardware: wrote %s (online=%s)\n' "$OUT" "$online"

package/bin/model-resolve.sh

@@ -0,0 +1,147 @@
+#!/usr/bin/env bash
+# model-resolve.sh — resolve a human model request to a concrete harness+model.
+#
+#   bin/model-resolve.sh resolve "qwen 3.6 iq2"
+#   bin/model-resolve.sh resolve "deepseek"
+#   bin/model-resolve.sh resolve "llama.cpp/qwen3.6-35b-a3b@q2_k_xl"
+#   bin/model-resolve.sh list
+#
+# Sources of truth: config/agents.yaml (providers, harness rule, local models)
+# and the live local catalog (`pi --list-models`). Local → pi, online → opencode.
+# Prints harness, provider, model, locality, confidence. Low confidence means the
+# caller should ASK the Allfather (ask_user_question), not guess.
+set -u
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+CFG="${YMIR_AGENTS_YAML:-$ROOT/config/agents.yaml}"
+
+case "${1-}" in -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;;
+  -h|--help|"") sed -n '2,12p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;; esac
+ACTION="${1:-resolve}"; shift || true
+REQ="${*:-}"
+
+python3 - "$ROOT" "$CFG" "$ACTION" "$REQ" <<'PY'
+import sys, os, re, subprocess
+root, cfg_path, action, req = sys.argv[1:5]
+try:
+    import yaml
+except Exception:
+    print("error: PyYAML missing"); sys.exit(1)
+cfg = yaml.safe_load(open(cfg_path)) or {}
+hcfg = cfg.get("harness") or {}
+LOCAL_H = hcfg.get("local") or "pi"
+ONLINE_H = hcfg.get("online") or "opencode"
+LOCAL_PROVIDERS = set(hcfg.get("local_providers") or [])
+providers = cfg.get("providers") or {}
+
+# online models the config already knows (default + every agent's model, non-local)
+online_models = set()
+_dm = cfg.get("default_model")
+if _dm and "/" in _dm:
+    online_models.add(_dm)
+for _a, _s in (cfg.get("agents") or {}).items():
+    _m = _s.get("model") if isinstance(_s, dict) else _s
+    if _m and "/" in _m:
+        _p = _m.split("/", 1)[0]
+        if _p not in LOCAL_PROVIDERS and "llama" not in _p and _p not in ("lmstudio",):
+            online_models.add(_m)
+
+def pi_catalog():
+    try:
+        out = subprocess.check_output(["pi", "--list-models"], text=True, stderr=subprocess.DEVNULL)
+    except Exception:
+        return []
+    rows = []
+    for line in out.splitlines():
+        p = line.split()
+        if len(p) >= 2 and "@" in p[1]:
+            rows.append((p[0], p[1]))
+    return rows
+
+catalog = pi_catalog()  # (provider, model) locally servable
+# local providers: from config + names that look local
+def is_local_provider(p):
+    return p in LOCAL_PROVIDERS or p.startswith("llama") or p in ("lmstudio",) or "llama" in p or p.startswith("llamacpp")
+
+QUANT_ALIAS = {"iq2":"q2_k_xl","iq-2":"q2_k_xl","q2":"q2_k_xl","iq1":"q2_k_xl",
+               "iq3":"iq3_s","q3":"iq3_s","q4":"q4_k_s","q5":"q5_k_m","q6":"q6_k","q8":"q8_0"}
+
+def tokens(s):
+    return re.findall(r"[a-z0-9]+(?:\.[0-9]+)?", s.lower())
+
+if action == "list":
+    loc = [m for p,m in catalog if is_local_provider(p)]
+    print(f'model-catalog{{local:{len(loc)}}}["{'" ,"'.join(sorted(set(loc)))}"]')
+    online = sorted({m for p in providers for m in (providers[p].get("models") or []) if isinstance(providers[p], dict)})
+    print(f'configured-online{len(online)}["{'" ,"'.join(online)}"]')
+    sys.exit(0)
+
+if not req.strip():
+    print("error: need a model request"); sys.exit(2)
+
+req_l = req.strip().lower()
+# 1. exact provider/model (optionally @quant)
+if "/" in req and "@" in req:
+    p, m = req.split("/", 1)
+    print(f'model-resolve[1]{{request,locality,harness,provider,model,confidence}}:\n  "{req}","{"local" if is_local_provider(p) else "online"}","{LOCAL_H if is_local_provider(p) else ONLINE_H}","{p}","{m}","exact"')
+    sys.exit(0)
+
+# 2. fuzzy against the local catalog
+rt = tokens(req_l)
+want_provider = None
+want_quant = None
+for t in rt:
+    if t in QUANT_ALIAS: want_quant = QUANT_ALIAS[t]
+    if t in ("local",): want_provider = "local"
+    if t in ("online","cloud","hosted"): want_provider = "online"
+
+best = None; best_score = 0.0
+for p, m in catalog:
+    if not is_local_provider(p): continue
+    mt = tokens(m)
+    score = float(sum(1 for t in rt if t in mt))
+    # quant proximity
+    if want_quant and want_quant.replace("_","") in m.replace("_",""):
+        score += 2
+    # family hints
+    if "qwen" in rt and "qwen" in m: score += 2
+    # tie-breaks: prefer newer version, then larger size (a more capable model)
+    ver = re.search(r"(\d+\.\d+)", m)
+    sz  = re.search(r"(\d+)b", m)
+    if ver: score += min(float(ver.group(1)), 9.0) / 100.0
+    if sz:  score += min(int(sz.group(1)), 100) / 1000.0
+    if score > best_score:
+        best_score = score; best = (p, m)
+
+if best and best_score >= 2:
+    conf = "high" if best_score >= 5 else "medium"
+    print(f'model-resolve[1]{{request,locality,harness,provider,model,confidence}}:\n  "{req}","local","{LOCAL_H}","{best[0]}","{best[1]}","{conf}"')
+    sys.exit(0)
+
+# 3. online: match a configured online provider by name
+for t in rt:
+    for pname, pspec in providers.items():
+        if pname.lower().replace(".","") in t.replace(".",""):
+            models = (pspec.get("models") or []) if isinstance(pspec, dict) else []
+            m = models[0] if models else ""
+            print(f'model-resolve[1]{{request,locality,harness,provider,model,confidence}}:\n  "{req}","online","{ONLINE_H}","{pname}","{m}","medium"')
+            sys.exit(0)
+
+# 3b. online: fuzzy against the configured online models
+best_o = None; best_os = 0
+for m in online_models:
+    p_, m_ = m.split("/", 1)
+    sc = sum(1 for t in rt if t in m_)
+    if sc > best_os:
+        best_os = sc; best_o = (p_, m_)
+if best_o and best_os >= 1:
+    print(f'model-resolve[1]{{request,locality,harness,provider,model,confidence}}:\n  "{req}","online","{ONLINE_H}","{best_o[0]}","{best_o[1]}","medium"')
+    sys.exit(0)
+
+# 4. unknown → ask
+print(f'model-resolve[1]{{request,resolution,ask}}:\n  "{req}","unresolved","yes"')
+print('help: bin/model-resolve.sh list  — or ask the Allfather with ask_user_question')
+sys.exit(0)
+PY