hal0ai 0.9.8__tar.gz

hal0ai-0.9.8/.claude/agents/docs-lead.md

@@ -0,0 +1,43 @@
+---
+name: docs-lead
+description: Sonnet section lead for hal0 documentation. Owns exactly one docs/ section (getting-started, concepts, guides, or reference+operate). Builds the change delta from git log, CHANGELOG.md, and graphify, decomposes it into per-file briefs, spawns docs-writer (haiku) workers to apply edits, reviews every diff, and optionally spawns docs-verifier to fact-check claims. Use for any docs update spanning multiple files in one section.
+model: sonnet
+---
+
+You are a documentation section lead for the hal0 repo. You own ONE section of
+`docs/` — the section is named in your task prompt. Never edit files outside it.
+
+## Workflow
+
+1. **Build the delta.** Read `CHANGELOG.md` (Unreleased + the last few released
+   sections), run `git log --oneline -- docs/ src/` to see what changed since
+   the docs were last touched, and use `graphify query "<question>"` /
+   `graphify explain "<concept>"` when `graphify-out/graph.json` exists to map
+   concepts to source. Verify any CLI flag, config key, endpoint, or path
+   against `src/hal0/` before it goes in a brief — never trust memory.
+2. **Decompose.** Group your section's files into 2–4 batches. For each batch
+   write a precise brief: file paths, exact facts to add/change/delete (with
+   the source citation: commit, CHANGELOG entry, or source file:line), and
+   what must NOT change.
+3. **Delegate.** Spawn one `docs-writer` (haiku) agent per batch via the Agent
+   tool with `model: "haiku"`. Run them concurrently. Writers only apply
+   briefs — all research and judgment stays with you.
+4. **Review.** `git diff` each writer's files. Fix style drift, factual
+   errors, and scope creep yourself with Edit. For risky claims (commands,
+   flags, defaults) spawn a `docs-verifier` (haiku) to check them against
+   source.
+5. **Report.** Return: files changed, one line per meaningful content change,
+   and any claims you could not verify. Do NOT commit — leave changes in the
+   working tree.
+
+## Ground rules
+
+- Docs are `.mdx`; match the existing file's heading style, frontmatter, tone,
+  and admonition components. No marketing language, no SEO filler.
+- Delete stale claims rather than hedging them ("previously…" belongs in the
+  CHANGELOG, not guides).
+- Retired concepts as of v0.9.5: slot `role` is gone (slot NAME is the routing
+  key, `hal0/<slot>`); profile slugs are the `{rocm,vulkan} × {dense,moe}`
+  grid; the installer does not seed a recommended model slot.
+- If a fact can't be verified in source, leave the doc untouched and flag it
+  in your report instead of guessing.

hal0ai-0.9.8/.claude/agents/docs-verifier.md

@@ -0,0 +1,25 @@
+---
+name: docs-verifier
+description: Haiku documentation fact-checker. Given a list of claims from updated docs (CLI commands, flags, config keys, defaults, paths, endpoints), verifies each against the hal0 source tree and reports verified/refuted/unverifiable with evidence. Read-only — never edits docs.
+model: haiku
+tools: Read, Grep, Glob, Bash
+---
+
+You fact-check documentation claims against the hal0 source tree. You never
+edit anything.
+
+For each claim in your task:
+
+- Find the authoritative source: CLI commands/flags in `src/hal0/cli*`,
+  config schema in `src/hal0/config*` / `src/hal0/schema*`, API routes in
+  `src/hal0/api/`, seeds under `installer/`, versioned behavior in
+  `CHANGELOG.md`. Use Grep/Glob; run `--help` output via Bash only if the
+  source is ambiguous.
+- Verdict per claim: VERIFIED (quote the source line as `path:line`),
+  REFUTED (quote what the source actually says), or UNVERIFIABLE (say what
+  you searched).
+- Be adversarial: a claim that is merely plausible is not verified. Check
+  defaults and spellings exactly — `chat = true` vs `chat=True` vs a stale
+  key name are different claims.
+
+Return a compact list: claim → verdict → evidence. Nothing else.

hal0ai-0.9.8/.claude/agents/docs-writer.md

@@ -0,0 +1,30 @@
+---
+name: docs-writer
+description: Haiku documentation writer. Applies a precise brief from a docs-lead to a small batch of .mdx files — adds, updates, or deletes exactly the facts listed in the brief, preserving each file's existing style. Does not research or invent content beyond the brief.
+model: haiku
+tools: Read, Edit, Write, Grep, Glob, Bash
+---
+
+You are a documentation writer executing a brief from a section lead. The
+brief lists file paths and the exact facts to add, change, or remove, with
+citations.
+
+Rules:
+
+- Edit ONLY the files named in your brief. Read each file fully before
+  editing.
+- Apply exactly the facts in the brief. If the brief cites a source file, you
+  may Read it to get wording/values right — but never add claims the brief
+  doesn't authorize.
+- Match the surrounding style: heading depth, frontmatter shape, code-fence
+  language tags, admonition components, sentence tone. A reader should not be
+  able to tell which paragraphs are new.
+- Delete stale content the brief marks stale — don't soften it into
+  "previously" phrasing.
+- Prose: complete sentences, no marketing language, no filler. Commands and
+  config keys in backticks, exact and copy-pasteable.
+- If something in the brief conflicts with what you see in the file or source,
+  do NOT guess — skip that item and report the conflict.
+
+Return: per file, a one-line summary of what changed, plus any skipped brief
+items with the reason.

hal0ai-0.9.8/.claude/settings.json

@@ -0,0 +1,24 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "CMD=$(python3 -c \"import json,sys; d=json.load(sys.stdin); print(d.get('tool_input',d).get('command',''))\" 2>/dev/null || true); case \"$CMD\" in *grep*|*rg\\ *|*ripgrep*|*find\\ *|*fd\\ *|*ack\\ *|*ag\\ *)   [ -f graphify-out/graph.json ] &&   echo '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"additionalContext\":\"MANDATORY: graphify-out/graph.json exists. You MUST run `graphify query \\\"<question>\\\"` before grepping raw files. Only grep after graphify has oriented you, or to modify/debug specific lines.\"}}'   || true ;; esac"
+          }
+        ]
+      },
+      {
+        "matcher": "Read|Glob",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "HIT=$(python3 -c \"import json,sys;d=json.load(sys.stdin);t=d.get('tool_input',d);exts=('.py','.js','.ts','.tsx','.jsx','.astro','.vue','.svelte','.go','.rs','.java','.rb','.c','.h','.cpp','.hpp','.cc','.cs','.kt','.swift','.php','.scala','.lua','.sh','.md','.rst','.txt','.mdx');vals=[str(t.get('file_path') or ''),str(t.get('pattern') or ''),str(t.get('path') or '')];j=' '.join(vals).lower().replace(chr(92),'/');tails=[('.'+x.rsplit('.',1)[-1]) for v in vals if v for x in [v.lower().replace(chr(92),'/').rsplit('/',1)[-1]] if '.' in x];sys.stdout.write('1' if 'graphify-out/' not in j and any(tl in exts for tl in tails) else '')\" 2>/dev/null || true); if [ \"$HIT\" = 1 ] && [ -f graphify-out/graph.json ]; then echo '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"additionalContext\":\"MANDATORY: graphify-out/graph.json exists. You MUST run graphify before reading source files. Use: `graphify query \\\"<question>\\\"` (scoped subgraph), `graphify explain \\\"<concept>\\\"`, or `graphify path \\\"<A>\\\" \\\"<B>\\\"`. Only read raw files after graphify has oriented you, or to modify/debug specific lines. This rule applies to subagents too \u2014 include it in every subagent prompt involving code exploration.\"}}'; fi || true"
+          }
+        ]
+      }
+    ]
+  }
+}

hal0ai-0.9.8/.github/workflows/agent-shim-smoke.yml

@@ -0,0 +1,170 @@
+name: Agent shim smoke (pi-coder + opencode nightly)
+
+# Nightly end-to-end re-run of each bundled agent's installer
+# (installer/agents/<agent>.sh) + an MCP round-trip against the resulting
+# hal0 MCP memory server.
+#
+# Why this exists:
+#   ADR-0004 §3 ("Mitigation for track-latest churn") + PLAN.md §17 risk
+#   row commit hal0 to a nightly smoke that catches upstream pi-coder
+#   contract drift overnight, instead of breaking real installs the next
+#   morning. Pinning pi-coder per hal0 release would freeze users on
+#   stale revisions; track-latest is the chosen tradeoff and this
+#   workflow is the safety net.
+#
+# Runner choice (v0.2):
+#   ubuntu-latest. Graduation to a self-hosted hal0-LXC runner with
+#   Strix Halo passthrough is a post-v0.2 follow-up — for v0.2 the
+#   round-trip only needs the FastAPI/MCP layer to be healthy, not the
+#   NPU/iGPU inference path.
+#
+# Failure handling:
+#   On red, open (or update) a single tracking issue tagged
+#   `agent-shim-broken`. One issue per upstream-broken-us state — we
+#   refuse to spam a fresh ticket every night while the same root cause
+#   is unfixed.
+
+on:
+  schedule:
+    # 04:00 UTC nightly — well after the Asia/Europe push window so any
+    # upstream pi-coder release from the prior day is already cut.
+    - cron: "0 4 * * *"
+  workflow_dispatch:
+
+concurrency:
+  group: agent-shim-smoke
+  # Latest nightly wins. We do not queue back-to-back runs.
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  issues: write   # required for the failure-issue handling step below
+
+jobs:
+  smoke:
+    name: ${{ matrix.agent }} install + MCP round-trip
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+    strategy:
+      fail-fast: false
+      matrix:
+        agent: [pi-coder, opencode]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install hal0 (editable + dev extras)
+        # Mirrors integration.yml — gets pip/pydantic/etc primed before
+        # installer/install.sh runs so the FastAPI process can boot.
+        run: |
+          python -m venv .venv
+          . .venv/bin/activate
+          pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Verify Docker on runner
+        # pi-coder.sh and the agent toolboxes rely on docker; surface a
+        # clear error early instead of letting smoke-pi-coder.sh fail
+        # deep inside install.
+        run: |
+          docker version
+          docker info --format '{{.ServerVersion}}'
+
+      - name: Run ${{ matrix.agent }} smoke
+        id: smoke
+        # The script is the contract — see scripts/smoke-${{ matrix.agent }}.sh
+        # header for exit-code semantics.
+        run: bash scripts/smoke-${{ matrix.agent }}.sh
+
+      - name: Capture journald on failure
+        if: failure()
+        run: |
+          sudo journalctl -u 'hal0-api*' --no-pager -n 500 > journal-api.log || true
+          sudo journalctl -u 'hal0-mcp*' --no-pager -n 500 > journal-mcp.log || true
+          systemctl status hal0-api.service --no-pager > status-api.txt 2>&1 || true
+
+      - name: Upload diagnostics on failure
+        if: failure()
+        uses: actions/upload-artifact@v7
+        with:
+          name: agent-shim-smoke-logs
+          path: |
+            journal-api.log
+            journal-mcp.log
+            status-api.txt
+          if-no-files-found: ignore
+
+  # ── failure-issue handling ────────────────────────────────────────────
+  # Runs only when the smoke job failed. Opens a fresh issue tagged
+  # `agent-shim-broken` if none is open, or comments on the existing one
+  # with the failing run's URL. This guarantees exactly one open ticket
+  # per upstream-broken-us state — no spam, no duplicates.
+  notify:
+    name: Open/update agent-shim-broken issue
+    needs: smoke
+    if: failure()
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      issues: write
+    steps:
+      - name: Find or create tracking issue
+        uses: actions/github-script@v9
+        env:
+          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const label = 'agent-shim-broken';
+            const runUrl = process.env.RUN_URL;
+            const today = new Date().toISOString().slice(0, 10);
+
+            // Look for any open issue with the label. We want one
+            // tracker per upstream-broken-us state, so we attach to the
+            // first match and never open duplicates.
+            const open = await github.paginate(github.rest.issues.listForRepo, {
+              owner: context.repo.owner,
+              repo:  context.repo.repo,
+              state: 'open',
+              labels: label,
+              per_page: 100,
+            });
+
+            const body = [
+              `Nightly agent-shim smoke failed on ${today}.`,
+              ``,
+              `Run: ${runUrl}`,
+              ``,
+              `This is the track-latest mitigation defined in ADR-0004 §3.`,
+              `Likely cause: an upstream bundled agent (pi-coder / opencode)`,
+              `changed a CLI flag, shim contract, or MCP handshake — check`,
+              `which matrix lane failed. Diagnose with the run log +`,
+              `\`agent-shim-smoke-logs\` artifact attached to the run.`,
+            ].join('\n');
+
+            if (open.length === 0) {
+              const created = await github.rest.issues.create({
+                owner: context.repo.owner,
+                repo:  context.repo.repo,
+                title: `agent-shim-broken: bundled-agent nightly failing (${today})`,
+                body,
+                labels: [label],
+              });
+              core.info(`opened issue #${created.data.number}`);
+            } else {
+              const issue = open[0];
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo:  context.repo.repo,
+                issue_number: issue.number,
+                body: `Still failing on ${today}.\n\nRun: ${runUrl}`,
+              });
+              core.info(`updated issue #${issue.number}`);
+            }

hal0ai-0.9.8/.github/workflows/bootstrap-parity.yml

@@ -0,0 +1,74 @@
+name: Bootstrap parity (daily)
+
+# Detect drift between the in-tree, audited installer/bootstrap.sh and the
+# LIVE one-liner served at https://hal0.dev/install.sh (hal0-web's mirrored
+# public/install.sh — what `curl https://hal0.dev/install.sh | bash` runs).
+#
+# Why this is NOT a required PR check:
+#   The check depends on the live public site. Network flakiness or a known,
+#   not-yet-synced drift would block every unrelated PR. Instead it runs on a
+#   daily schedule and on demand, surfacing drift in the run output so the
+#   installer team can reconcile hal0-web in a follow-up. The header of
+#   bootstrap.sh promises the two stay mirrored; this is the safety net.
+#
+# The script is the contract (scripts/check-bootstrap-parity.sh):
+#   exit 0 — in sync.   exit 1 — drift (unified diff printed).
+#   exit 2 — operational error (fetch failed / empty) — NOT read as drift.
+
+on:
+  schedule:
+    # 06:00 UTC daily — early enough that a fresh drift is visible at the
+    # start of the working day across the Americas/EU.
+    - cron: "0 6 * * *"
+  workflow_dispatch:
+
+concurrency:
+  group: bootstrap-parity
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  parity:
+    name: Diff in-tree bootstrap.sh against live install.sh
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+
+    steps:
+      - name: Checkout hal0
+        uses: actions/checkout@v6
+
+      - name: Run bootstrap-parity check
+        id: parity
+        # Exit 0 = in sync, 1 = drift, 2 = operational error. We surface the
+        # script's stdout/stderr (the unified diff lives there) into the step
+        # summary so a glance at the run page tells the whole story.
+        run: |
+          set +e
+          bash scripts/check-bootstrap-parity.sh > parity.out 2>&1
+          rc=$?
+          set -e
+
+          {
+            echo "## Bootstrap parity check"
+            echo ""
+            echo '```diff'
+            cat parity.out
+            echo '```'
+          } >> "$GITHUB_STEP_SUMMARY"
+
+          cat parity.out
+
+          case "$rc" in
+            0)
+              echo "::notice::installer/bootstrap.sh is in sync with the live install.sh."
+              ;;
+            1)
+              echo "::error::DRIFT — installer/bootstrap.sh differs from the live hal0.dev/install.sh. Sync hal0-web:public/install.sh."
+              ;;
+            *)
+              echo "::warning::Could not fetch the live installer (operational error, exit ${rc}). NOT treated as drift."
+              ;;
+          esac
+          exit "$rc"

hal0ai-0.9.8/.github/workflows/ci.yml

@@ -0,0 +1,100 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+# Cancel superseded PR runs to save runners; never cancel a push to main
+# (every main commit must build — required checks + the nightly greenness gate).
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+# Least privilege: CI only needs to read the repo.
+permissions:
+  contents: read
+
+jobs:
+  python:
+    runs-on: ubuntu-latest
+    # 3.14 is experimental until every dep ships 3.14 wheels — surface it
+    # without reddening main. No-op on PRs, which run 3.12 only.
+    continue-on-error: ${{ matrix.python-version == '3.14' }}
+    env:
+      # fastembed (cognee memory tests) honours FASTEMBED_CACHE_PATH
+      # (fastembed/common/utils.py). Pin it to a stable, cacheable dir so the
+      # warm step AND pytest share one location that actions/cache persists.
+      FASTEMBED_CACHE_PATH: ${{ github.workspace }}/.fastembed-cache
+    strategy:
+      fail-fast: false
+      matrix:
+        # PRs test the primary 3.12 only (fast feedback; matches the required
+        # "python (3.12)" status check). Pushes to main test the full supported
+        # range so Python-version drift still gates the protected branch.
+        python-version: ${{ (github.event_name == 'pull_request' && fromJSON('["3.12"]')) || fromJSON('["3.12","3.13","3.14"]') }}
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - name: Install system deps
+        # ffmpeg backs the in-container moonshine audio decoder
+        # (packaging/toolbox/moonshine/moonshine_server.py). The redaction
+        # tests in tests/providers/test_moonshine_server.py exercise the
+        # real subprocess path; without ffmpeg they hit FileNotFoundError
+        # instead of the CalledProcessError the code catches.
+        run: sudo apt-get update && sudo apt-get install -y --no-install-recommends ffmpeg
+      - name: Install
+        run: pip install -e ".[dev]"
+      - name: Cache fastembed embedding model
+        # cognee memory tests (tests/memory/test_cognee_wrapper.py) embed via
+        # fastembed, which downloads qdrant/bge-small-en-v1.5-onnx-q (~64 MB)
+        # into FASTEMBED_CACHE_PATH on first use. That per-run download
+        # intermittently slow-fails (could-not-load-model-from-any-source) and
+        # gated unrelated PRs (#442, #445). The model id is fixed, so a static
+        # key caches once and restores forever (bump -vN to refresh).
+        uses: actions/cache@v5
+        with:
+          path: ${{ github.workspace }}/.fastembed-cache
+          key: fastembed-bge-small-en-v1.5-v2
+      - name: Warm fastembed cache
+        # On a cache miss, download the model now. fastembed already retries 3x
+        # internally; we wrap each attempt in `timeout` so a stalled connection
+        # is bounded (~6 min) and retried fresh rather than hanging. Best-effort:
+        # on total failure, let pytest surface the error rather than masking it.
+        run: |
+          for attempt in 1 2 3; do
+            timeout 360 python -c "from fastembed import TextEmbedding; TextEmbedding('BAAI/bge-small-en-v1.5'); print('fastembed model warmed')" && exit 0
+            echo "::warning::fastembed warm attempt $attempt failed/timed out; retrying in 10s"
+            sleep 10
+          done
+          echo "::warning::fastembed warm-up failed after 3 attempts; cognee tests will surface it"
+      - name: Lint
+        run: ruff check src tests
+      - name: Format check
+        run: ruff format --check src tests
+      - name: Test
+        # Coverage (+ verbose) only on main pushes — it's a report, not a gate,
+        # so PRs skip the instrumentation overhead and run a quiet, faster suite.
+        run: pytest tests/ ${{ github.event_name == 'push' && '-v --cov=hal0 --cov-report=term-missing' || '-q' }}
+
+  ui:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: ui
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "22"
+          cache: npm
+          cache-dependency-path: ui/package-lock.json
+      - name: Install
+        run: npm ci
+      - name: Lint
+        run: npm run lint
+      - name: Build
+        run: npm run build