Skip to content

Add managed llama.cpp lifecycle and settings on macOS arm64 - #60

Open
JaredP94 wants to merge 4 commits into
mainfrom
feat/llamacpp-engine
Open

JaredP94 wants to merge 4 commits into
mainfrom
feat/llamacpp-engine

Conversation

@JaredP94

@JaredP94 JaredP94 commented Nov 6, 2026 •

Copy link
Copy Markdown
Owner

Description

Add llama.cpp as a PAIR-managed engine on macOS arm64: install, start/stop, runtime status, server port, launch arguments and environment. This is PR 1 of 4, adapting selected lifecycle concepts from NVIDIA/Personal-AI-Router@6d2d67f, with upstream author credit on each commit. NVIDIA#153 informs identity-bound installation/removal; NVIDIA#186 remains deferred.

The official b12171 archive is pinned to SHA-256 870ef967970fa18bbd31460bc5f7929bbb5f091359d8dc0f58e20133aa4b5fcd. The macOS build is not notarized, like PAIR itself; the engine lists and documentation say so. It does not serve requests through PAIR yet.

Scope

  • Bounded tar.gz staging with strip-one-component semantics, contained internal links, required server/library layout (Metal resources are embedded), checksum verification, quarantine rejection, and /usr/bin/codesign --verify --strict using argv. Never clear quarantine or re-sign.
  • Atomic first install and owned-directory exchange on update, identity-bound claims, failed-validation rollback, uninstall preserving the sibling LLAMA_CACHE directory. Updating requires stopping the engine first; clients never uninstall it before an update.
  • Default 127.0.0.1:8082, collision/reservation checks, /props JSON role=router readiness, existing validated LAN-bind path, audited protected listener flags/environment and underscore aliases. Complete audit: services/nvpair-engine-manager/LLAMACPP.md.
  • Proxy-free engine settings with existing revision/recovery protocol (proxyPort=0), minimal desktop/TUI lifecycle list support and original repository-native icon. No load profiles.
  • Engine-manager 1.5.0 (minor relative to v0.9.0's 1.4.0), broker 2.6.0, TUI 1.4.0.
  • Deferred PR 2: proxy worker, discovery and routing. PR 3: Go model hub/download/delete. PR 4: remaining desktop/TUI and release integration. No new worker or unified-proxy plumbing. No Windows process-ownership files changed.

Validation

Local macOS arm64, fixture-only; no downloaded release executable run and no real engine installed:

  • In each touched Go module (nvpair-engine-manager, nvpair-ui-broker, nvpair-tui): gofmt -l, go vet ./..., GOOS=linux go vet ./..., GOOS=windows go vet ./..., go test -count=1 ./... — all pass (format output empty).
  • Own worktree desktop: npm ci --no-audit --no-fund; npm run -s typecheck, npm run -s lint (zero warnings), npm run -s test:unit (95 files / 944 tests), npm run -s dead-code:check, npm run -s service-contracts:write, npm run -s service-contracts:check — pass; generated API documentation unchanged.
  • node scripts/spdx-headers.mjs: 0 missing; git diff --check: clean. pgrep -lf 'fake-engine|llama-server': no survivors.
  • New fixture coverage includes TestArchiveContainment, TestArchiveLimitsAndCancellation, TestArchiveChecksumMismatch, TestArchiveQuarantinePreservedAndRejected, TestArchiveQuarantinedSourceRejected, TestArchiveSignatureIntegrity, TestArchiveCodesignUnavailable, TestArchiveInstallRollback, TestArchiveExecutorInstallUpdateRollback, TestArchiveAtomicUpdate, TestArchiveUninstallPreservesModelCacheAndRequiresClaim, TestArchiveManifestValidation, TestLlamaProtectedLaunchInputs, TestLlamaReadinessIdentity, TestLlamaPortCollision, plus broker proxy-free settings/recovery and desktop/TUI lifecycle/update tests. Regression tests observed failing before fixes and passing afterward.
  • Cross-process tests were not run locally. Final CI run 42251407665, commit 7bbe62b3: Desktop checks, SPDX headers, Go modules (ubuntu-latest), and Cross-process tests (ubuntu-latest) all pass. The Go modules job includes the full engine-manager race suite and repeated downloader shutdown regressions.
  • Downloaded cross-process-ubuntu-latest from that final run into fresh directory /tmp/pair-llamacpp-final-artifact.6LBRgZ; python3 -I /tmp/pair-review/scripts/noskip.py /tmp/pair-llamacpp-final-artifact.6LBRgZ/cross-process.jsonl reports 123 pass, zero skips/failures.
  • Both macOS jobs, Go modules (macos-15) and Cross-process tests (macos-15), never acquired a runner: empty runner name, zero steps, then cancelled after 15 minutes, in both runs. Consequently 4/6 jobs pass; CI is not fully green, and hosted macOS coverage remains unverified. No workflow or runner workaround was added.
  • Initial Linux module CI exposed two ownership fixtures placed in platform-independent files. Their success-path directory claims rely on macOS birth-time identities; Linux intentionally uses change-time identities. Moved these fixtures unchanged into the Darwin suite, retaining portable extraction/checksum/manifest tests on Linux. Native archive tests/full suite and all three vet targets pass after this test-only correction; final Linux CI passes.

Risk

Other platforms are explicitly unsupported for this engine. Checksum and existing ad-hoc signature integrity do not establish publisher trust or notarization. Installation fails closed on quarantine, a broken signature or unavailable codesign. No quarantine attributes are removed, and no signatures are changed.

Packaged macOS arm64 live install/update/rollback and start/stop smoke checks remain the maintainer's pre-merge task; no live llama.cpp run is claimed. The two hosted macOS jobs also remain a pre-merge gate because no runner was acquired. Independent automated review could not complete (reviewer timeouts); local source/diff review and the checks above completed. This PR is not an inference or release certification.

Checklist

  • I have read the Contributing Guidelines.
  • Every commit is signed off (git commit -s), certifying the Developer Certificate of Origin.
  • New or existing tests cover the change.
  • Relevant documentation is updated.
  • I checked the diff, changed filenames, and commit messages for credentials, private data, internal URLs, internal issue identifiers, and generated artifacts.
  • I recorded the validation commands and results above.
  • I bumped any affected component in services/versions.json, and described user-visible changes above so they reach the release notes.

JaredP94 and others added 4 commits November 6, 2026 17:06
Add a bounded tar.gz installer with contained library links, required-file verification, unchanged quarantine attributes and strict existing-signature checks. Stage identity-bound claims with the artifact and atomically exchange owned macOS installations, leaving failed installs and updates unchanged. Preserve sibling model caches on uninstall. This prepares the lifecycle-only port of NVIDIA/Personal-AI-Router@6d2d67f without its proxy plumbing.

Co-authored-by: Terve <ntervalon@nvidia.com>
Signed-off-by: Jared Ping <13906915+JaredP94@users.noreply.github.com>
Adapt the lifecycle-only manifest from NVIDIA/Personal-AI-Router@6d2d67f to the fork, pin b12171 and require its complete server library layout. Protect every audited listener control and port-changing preset, including vendor underscore spellings and inherited environment. Require the /props router identity for readiness and health. Document the unnotarized release, port 8082, retained cache and deferred routing/model integration.

Co-authored-by: Terve <ntervalon@nvidia.com>
Signed-off-by: Jared Ping <13906915+JaredP94@users.noreply.github.com>
Expose llama.cpp installation, runtime state and protected server launch settings without a proxy or model routing. Keep settings revision recovery and collision checks in Go, display the unnotarized build notice, and preserve atomic archive updates from desktop and TUI clients.

Adapt the lifecycle-only scope from NVIDIA/Personal-AI-Router@6d2d67f and its follow-ups NVIDIA#153 and NVIDIA#186; the proxy and model hub remain deferred. Reject quarantined source archives without altering their attributes and extend fixture coverage.

Co-authored-by: Terve <ntervalon@nvidia.com>
Signed-off-by: Jared Ping <13906915+JaredP94@users.noreply.github.com>
The supported archive installer relies on macOS birth-time identities surviving staging-marker writes and directory exchange. Linux intentionally uses change time, so successful directory-claim fixtures cannot describe an install on that unsupported platform. Keep these rollback and cache-preserving uninstall tests in the native Darwin suite while retaining portable extraction, checksum and manifest coverage everywhere. CI exposed both misplaced fixtures; the native suite and cross-platform compilation now pass.

Signed-off-by: Jared Ping <13906915+JaredP94@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant