diff --git a/.github/workflows/v2-ci.yml b/.github/workflows/v2-ci.yml index ed57da8313..bd34ef89c7 100644 --- a/.github/workflows/v2-ci.yml +++ b/.github/workflows/v2-ci.yml @@ -905,6 +905,7 @@ jobs: node --check bin/lib/pane-classifier.js bash -n bin/contributor-relay.sh node bin/contributor-relay.test.js + node --test bin/mlx-backend.test.js # bin/vibe-kanban-mirror.js (#10641): report-only hive → vibe-kanban # mirror, exercised against a fake MCP stdio server. diff --git a/Justfile b/Justfile index 8b3825a7bf..583b09eba2 100644 --- a/Justfile +++ b/Justfile @@ -37,6 +37,53 @@ contributor_cpu_limit := "2" default: @just --list +# Explicitly verifies streaming tool calls against an already-running local +# MLX-LM server, then persists only Pi's mlx provider. Never downloads weights. +[positional-arguments] +contribute-mlx-setup model verify: + node bin/mlx-backend.js configure "$1" "$2" + +# Starts only an explicitly chosen, already-downloaded model on Mac loopback. +[positional-arguments] +contribute-mlx-serve model: + node bin/mlx-backend.js serve "$1" + +# Apple MLX is an inference engine for Pi, not a separate coding CLI. +[positional-arguments] +contribute-mlx mode="docker": + #!/usr/bin/env bash + set -euo pipefail + _MLX_REQUESTED_MODEL="${AGENT_MODEL:-}" + _MLX_REQUESTED_RUNTIME="${HIVE_CONTAINER_RUNTIME:-}" + if [[ -f "{{config_dir}}/contributor.env" ]]; then + source "{{config_dir}}/contributor.env" + fi + if [[ -n "$_MLX_REQUESTED_MODEL" ]]; then + AGENT_MODEL="$_MLX_REQUESTED_MODEL" + fi + if [[ -n "$_MLX_REQUESTED_RUNTIME" ]]; then + HIVE_CONTAINER_RUNTIME="$_MLX_REQUESTED_RUNTIME" + fi + if [[ "${AGENT_MODEL:-}" != mlx/* ]]; then + echo "ERROR: Select your verified MLX model first: export AGENT_MODEL=mlx/" + echo " Setup: just contribute-mlx-setup --verify-tools" + exit 1 + fi + case "$1" in + docker) + if [[ "${HIVE_CONTAINER_RUNTIME:-docker}" != "docker" ]]; then + echo "ERROR: Apple MLX requires Docker Desktop 4.34+ host networking, not Podman machine." + exit 1 + fi + export HIVE_CONTAINER_RUNTIME=docker + ;; + local) ;; + *) echo "ERROR: MLX mode must be docker or local; Kubernetes cannot reach Mac loopback."; exit 1 ;; + esac + export AGENT_MODEL + export HIVE_MLX_LAUNCH_MODEL="$AGENT_MODEL" + just --justfile "{{justfile_directory()}}/Justfile" contribute-hive pi "$1" + # Run the live run-level acceptance test (#8466 layer 2). Requires HIVE_URL and # HIVE_TOKEN like the rest of src/test, plus HIVE_RUNS_E2E_KEY or # HIVE_RUNS_E2E_REPO/HIVE_RUNS_E2E_ISSUE for the pinned run/spec issue. @@ -178,6 +225,9 @@ contribute-check-backend backend="claude": exit 1 fi echo "HIVE_BACKEND_READINESS=${PI_READINESS}" + if [[ "${AGENT_MODEL}" == mlx/* ]]; then + node bin/mlx-backend.js check "${AGENT_MODEL}" + fi echo " Credential presence is reported as configured_unverified, never as proof of authentication." else echo "ERROR: Pi CLI not found. Install: curl -fsSL https://pi.dev/install.sh | sh" @@ -925,6 +975,7 @@ contribute-hive backend="" mode="docker": check-version echo "Not set up yet. Run: just contribute-setup " exit 1 fi + _MLX_LAUNCH_MODEL="${HIVE_MLX_LAUNCH_MODEL:-}" set -a source "{{config_dir}}/gh-auth.env" source "{{config_dir}}/contributor.env" @@ -957,6 +1008,16 @@ contribute-hive backend="" mode="docker": check-version BACKEND="${AGENT_BACKEND:-claude}" fi export AGENT_BACKEND="$BACKEND" + # MLX-only launch override: preserve an explicit selection over saved profiles. + if [[ -n "${_MLX_LAUNCH_MODEL:-}" ]]; then + if [[ "$BACKEND" != "pi" || "$_MLX_LAUNCH_MODEL" != mlx/* ]]; then + echo "ERROR: MLX launcher requires the Pi backend and an mlx/ selection." + exit 1 + fi + export AGENT_MODEL="$_MLX_LAUNCH_MODEL" + fi + unset HIVE_MLX_LAUNCH_MODEL _MLX_LAUNCH_MODEL + # End MLX-only launch override. # Bob has no headless credential other than its API key — without it the # agent would launch and sit at Bob's key prompt forever. Fail fast. if [[ "$BACKEND" == "bob" && -z "${BOB_API_KEY:-}" && -z "${BOBSHELL_API_KEY:-}" ]]; then @@ -972,6 +1033,9 @@ contribute-hive backend="" mode="docker": check-version exit 1 fi echo "HIVE_BACKEND_READINESS=${PI_READINESS}" + if [[ "${AGENT_MODEL}" == mlx/* ]]; then + node bin/mlx-backend.js check "${AGENT_MODEL}" + fi # This recipe runs in its own shell, so narrowing the environment does not # alter the contributor's login shell. It does ensure both local relay/CLI # launches and the container path can see only the selected provider's @@ -1276,6 +1340,9 @@ contribute-hive backend="" mode="docker": check-version # Same canonical selection used by the container entrypoint and every # relay restart. %q keeps model IDs with shell metacharacters one argv. PERM_FLAG="${PERM_FLAG:+${PERM_FLAG} }--model $(printf %q "$AGENT_MODEL")" + if [[ "$AGENT_MODEL" == mlx/* ]]; then + PERM_FLAG+=" --extension $(printf %q "{{justfile_directory()}}/bin/mlx-pi-extension.js")" + fi fi # Create tmux session with the CLI. @@ -1683,6 +1750,11 @@ contribute-hive backend="" mode="docker": check-version fi ;; pi) + if [[ "${AGENT_MODEL:-}" == mlx/* && "$(uname -s)" == "Darwin" && "$RUNTIME" != "docker" ]]; then + echo "ERROR: MLX container mode on macOS requires Docker Desktop 4.34+ with host networking enabled." + echo " Podman machine host networking reaches its Linux VM, not the Mac's loopback MLX server." + exit 1 + fi if [ -d "${HOME}/.pi" ]; then stage_copy "${HOME}/.pi" ".pi" # Keep only the selected provider's official auth/custom-provider diff --git a/bin/README.md b/bin/README.md index 256076be69..7c79a7607b 100644 --- a/bin/README.md +++ b/bin/README.md @@ -88,6 +88,8 @@ Most production scripts are installed under `/usr/local/bin` by `bin/hive-deploy | `contributor-quota-control.js` | Contributor runtime | Out-of-band contributor quota override command (#6953). The relay usually runs detached (background, container, K8s pod), so #6833's scoped overrides cannot depend on its stdin; this writes `continue-once` / `continue-until-reset` / `disable-session` / `pause-until-reset` / `resume` overrides into the same per-pool directory (`lib/quota-pool-store.js`) the relay reads on every guard evaluation. Stores only the relay's own published hold state — never a provider credential, raw account identifier, or billing figure. | | `lib/quota-pool-store.js` | Contributor runtime | Shared per-pool quota-override store used by both `contributor-relay.js` (guard evaluation) and `contributor-quota-control.js` (override writes), so the attached banner and the out-of-band command share exactly one mechanism with no second code path to drift (#6953). | | `pi-backend.js` | Contributor runtime | Pi contributor adapter contract (#5039). `AGENT_MODEL` is the one contributor-owned selection input; the adapter derives the provider's official credential variable names from it so only the selected provider's keys are handed to the container. | +| `mlx-backend.js` | Optional local inference | Apple Silicon runtime/config checks, explicit tool-call verification and offline loopback server launch for Pi's `mlx` provider. Use `just contribute-mlx-serve`, `just contribute-mlx-setup --verify-tools`, then `just contribute-mlx`; see [MLX setup](../src/docs/contributor-relay.md#apple-mlx-local-inference). No automatic installation or model downloads. | +| `mlx-pi-extension.js` | Optional local inference | Delegates streaming/tools to Pi's maintained OpenAI adapter with a loopback-only, redirect-rejecting transport; required for the private `hive-mlx` API. | | `omp-backend.js` | Contributor runtime | omp (Oh My Pi) contributor adapter (#7678). Container mode stages the host's omp sign-in — `~/.omp/agent/config.yml` plus the `agent.db` SQLite store whose `auth_credentials` rows hold every provider's OAuth record or API key; omp has no `auth.json` — into the ephemeral CLI staging dir and, like `pi-backend.js --stage`, keeps only the selected provider's rows (`AGENT_MODEL=provider/model`, else `config.yml`'s `modelRoles`). `--describe` is what `just contribute-setup omp` prints so a missing host sign-in is caught before a container opens on omp's setup wizard. `--stage` and `--describe` refuse/flag a row omp has marked `disabled_cause` (a revoked OAuth refresh), and `--sync-back` writes a credential the container refreshed back over the host row it was staged from — only the selected provider's existing row, only when strictly newer — so a single-use refresh token consumed in the container does not strand the host; `just contribute-hive omp` runs it every `HIVE_OMP_CREDENTIAL_SYNC_SECONDS` (default 300) while the container runs and once more at exit (#7922). | ## Model, token, and experiment helpers diff --git a/bin/contributor-agent.sh b/bin/contributor-agent.sh index db443734bf..d8de168717 100755 --- a/bin/contributor-agent.sh +++ b/bin/contributor-agent.sh @@ -618,6 +618,9 @@ if [[ "${HIVE_CONTRIBUTOR_AGENT_TEST_LINK_KNOWLEDGE:-}" == "1" ]]; then fi validate_pi_selection() { + if [[ "${AGENT_MODEL:-}" == mlx/* ]]; then + node "${SCRIPT_DIR}/mlx-backend.js" check "${AGENT_MODEL}" --endpoint-only >&2 || return + fi node "${SCRIPT_DIR}/pi-backend.js" "${AGENT_MODEL:-}" } @@ -1149,6 +1152,9 @@ if [[ -n "${AGENT_MODEL:-}" ]]; then *) MODEL_FLAG="--model $AGENT_MODEL" ;; esac fi +if [[ "$AGENT_BACKEND" == "pi" && "${AGENT_MODEL:-}" == mlx/* ]]; then + MODEL_FLAG+=" --extension $(printf %q "${SCRIPT_DIR}/mlx-pi-extension.js")" +fi REASONING_FLAG="" if [[ "$AGENT_BACKEND" == "codex" && -n "${AGENT_REASONING_EFFORT:-}" ]]; then REASONING_FLAG="-c 'model_reasoning_effort=\"${AGENT_REASONING_EFFORT}\"'" diff --git a/bin/contributor-relay.js b/bin/contributor-relay.js index 050826be0e..52b5741c8f 100755 --- a/bin/contributor-relay.js +++ b/bin/contributor-relay.js @@ -47,6 +47,7 @@ const { redactPiCredentials, piReadiness, } = require('./pi-backend.js'); +const { checkRuntime: checkMlxRuntime } = require('./mlx-backend.js'); // Pure pane-classification (kubestellar/hive#6429): readiness/login/onboarding // tables, the busy/idle/blocked/error state machine, the blocked-on-human // reason breakdown, the modal-dismiss keystroke table, and the pane-tail/ @@ -3224,6 +3225,10 @@ function resolveBackendShell() { // play — agy's effort is conditional on exactly that. function modelFlagFor() { if (BACKEND === 'pi' && !PI_SELECTION.valid) throw new Error(PI_SELECTION.error); + if (BACKEND === 'pi') checkMlxRuntime(MODEL, PI_ENV); + if (BACKEND === 'pi' && PI_SELECTION.provider === 'mlx') { + return `--model ${MODEL} --extension ${shellQuote(path.join(__dirname, 'mlx-pi-extension.js'))}`; + } return MODEL && !NO_MODEL_FLAG_BACKENDS.includes(BACKEND) ? `--model ${MODEL}` : ''; } @@ -3919,6 +3924,7 @@ function buildHeadlessArgv(prompt) { const spec = HEADLESS_BACKENDS[BACKEND]; if (!spec) return null; if (BACKEND === 'pi' && !PI_SELECTION.valid) throw new Error(PI_SELECTION.error); + if (BACKEND === 'pi') checkMlxRuntime(MODEL, PI_ENV); const { cmd, perm } = resolveBackend(); const permArgs = perm ? perm.split(/\s+/).filter(Boolean) : []; const modelArgs = MODEL && !NO_MODEL_FLAG_BACKENDS.includes(BACKEND) ? ['--model', MODEL] : []; @@ -3937,7 +3943,9 @@ function buildHeadlessArgv(prompt) { const claudeEffortArgs = BACKEND === 'claude' && effectiveReasoningEffort() ? ['--effort', effectiveReasoningEffort()] : []; - const flagArgs = [...permArgs, ...modelArgs, ...reasoningArgs, ...agyEffortArgs, ...museEffortArgs, ...claudeEffortArgs]; + const mlxArgs = BACKEND === 'pi' && PI_SELECTION.provider === 'mlx' + ? ['--extension', path.join(__dirname, 'mlx-pi-extension.js')] : []; + const flagArgs = [...permArgs, ...modelArgs, ...mlxArgs, ...reasoningArgs, ...agyEffortArgs, ...museEffortArgs, ...claudeEffortArgs]; // Sub-command-first CLIs parse their options on the sub-command, not the // root binary, so the one-shot token has to lead (see flagsAfterCommand). const args = spec.flagsAfterCommand @@ -9901,6 +9909,15 @@ if (process.env.HIVE_RELAY_TEST_MODE === '1') { } process.exit(1); } + if (BACKEND === 'pi') { + try { checkMlxRuntime(MODEL, PI_ENV); } catch (error) { + console.error(`FATAL: ${error.message}`); + if (CONTRIBUTOR_MODE === MODE_HEADLESS) { + writeHeadlessStatus(HEADLESS_STATE_FAILED, { result: 'failed', reason: error.message }); + } + process.exit(1); + } + } // Warm the capability cache BEFORE the first hub connection. detectCapabilities() // is called from the auth_challenge handler, and the hub bounds a handshake at // 30s (wsAuthTimeout); doing the probes here keeps every one of them — backend diff --git a/bin/contributor-relay.test.js b/bin/contributor-relay.test.js index 7c90e9883b..e979b8dc92 100644 --- a/bin/contributor-relay.test.js +++ b/bin/contributor-relay.test.js @@ -34,7 +34,7 @@ const RELAY_PATH = path.join(__dirname, 'contributor-relay.js'); // bash and no WebSocket are ever touched. // --------------------------------------------------------------------------- -function loadRelay({ backend = 'copilot', backendBinary = null, backendPerm = '--allow-all', backendPermShell = null, model = '', reasoningEffort = '', cliStates = ['ready'], procAlive = true, mode = 'interactive', execFileResult = null, statusFile = null, paneText = null, env = null, cliVersion = null, attachedClients = false, attachedIdleMs = 0, clientActivityRaw = null, listClientsThrows = false, prMeta = null, sessionMissing = false, newSessionFails = false, gitStatus = '', ghIssueEditFailures = 0 } = {}) { +function loadRelay({ backend = 'copilot', backendBinary = null, backendPerm = '--allow-all', backendPermShell = null, model = '', reasoningEffort = '', cliStates = ['ready'], procAlive = true, mode = 'interactive', execFileResult = null, statusFile = null, paneText = null, env = null, cliVersion = null, attachedClients = false, attachedIdleMs = 0, clientActivityRaw = null, listClientsThrows = false, prMeta = null, sessionMissing = false, newSessionFails = false, gitStatus = '', ghIssueEditFailures = 0, mlxPreflightError = null } = {}) { const commands = []; // #7924: how many `gh issue edit` calls fail before one succeeds — models a // label the repository does not define (the first add fails, the relay @@ -253,6 +253,11 @@ function loadRelay({ backend = 'copilot', backendBinary = null, backendPerm = '- }; const stubs = { + './mlx-backend.js': { + checkRuntime(raw) { + if (raw.startsWith('mlx/') && mlxPreflightError) throw mlxPreflightError; + }, + }, child_process: { execSync: fakeExecSync, execFile: fakeExecFile, @@ -2334,6 +2339,51 @@ test('Pi revoke kills the child and rejects a raced stale completion', () => { } finally { teardown(relay); } }); +test('MLX uses the real Pi task argv, model receipts and cancellation contract', () => { + const model = 'mlx/mlx-community/tool-coder-4bit'; + const relay = loadRelay({ backend: 'pi', backendPerm: '', mode: 'headless', model, cliVersion: 'pi 1.4.0' }); + try { + assert.deepStrictEqual(relay.buildHeadlessArgv('edit and test').args, + ['--model', model, '--extension', path.join(__dirname, 'mlx-pi-extension.js'), '--print', '--mode', 'json', 'edit and test']); + const task = { task_id: 'mlx-1', task_gen: 17, kind: 'issue', repo: 'x/y', number: 1, title: 'MLX' }; + relay.setCurrentTask(task); + relay.runHeadlessTask(task); + const complete = relay.__sent.find(m => m.type === 'task_complete'); + assert.ok(complete); + assert.strictEqual(complete.cli_backend, 'pi'); + assert.strictEqual(complete.provider, 'mlx'); + assert.strictEqual(complete.model, model); + } finally { teardown(relay); } + const waiting = loadRelay({ backend: 'pi', mode: 'headless', model, cliVersion: 'pi 1.4.0', execFileResult: { defer: true } }); + try { + const task = { task_id: 'mlx-cancel', task_gen: 18, kind: 'issue', repo: 'x/y', number: 2, title: 'cancel' }; + waiting.setCurrentTask(task); + waiting.runHeadlessTask(task); + const child = waiting.getHeadlessChild(); + waiting.handleMessage(JSON.stringify({ type: 'task_revoke', task_id: task.task_id, reason: 'operator stop' })); + assert.strictEqual(child.killed, true); + waiting.__completeDeferredExecFile(null, 'late success', ''); + assert.ok(!waiting.__sent.some(m => m.type === 'task_complete')); + } finally { teardown(waiting); } +}); + +test('MLX endpoint failure refuses execution rather than falling back to a hosted Pi model', () => { + const relay = loadRelay({ + backend: 'pi', mode: 'headless', model: 'mlx/mlx-community/tool-coder-4bit', + mlxPreflightError: new Error('MLX local endpoint request failed'), + }); + try { + assert.throws(() => relay.buildHeadlessArgv('edit'), /local endpoint/); + assert.throws(() => relay.buildLaunchCommand(), /local endpoint/); + const task = { task_id: 'mlx-fail', task_gen: 19, kind: 'issue', repo: 'x/y', number: 3, title: 'fail' }; + relay.setCurrentTask(task); + relay.runHeadlessTask(task); + assert.ok(relay.__sent.some(m => m.type === 'task_failed')); + assert.ok(!relay.__sent.some(m => m.type === 'task_complete')); + assert.ok(!relay.__execFileCalls.some(call => call.bin === 'pi'), 'failed MLX preflight must not start a coding agent'); + } finally { teardown(relay); } +}); + // --------------------------------------------------------------------------- // hivecommons/hive#7778 — a headless task must keep renewing the hub's progress // lease while its child is alive. diff --git a/bin/mlx-backend.js b/bin/mlx-backend.js new file mode 100644 index 0000000000..c3f8f7e169 --- /dev/null +++ b/bin/mlx-backend.js @@ -0,0 +1,310 @@ +'use strict'; + +// MLX-LM supplies inference; Pi supplies the coding tools and task lifecycle. +// Only the explicit serve command starts a server; nothing installs packages +// or downloads weights. +const fs = require('fs'); +const path = require('path'); +const { execFileSync } = require('child_process'); +const { createHash } = require('crypto'); +const { parsePiModelSelection } = require('./pi-backend.js'); + +const DEFAULT_ENDPOINT = 'http://127.0.0.1:8080/v1'; +const HTTP_TIMEOUT_MS = 10000; +const PROBE_TIMEOUT_MS = 120000; +const MAX_RESPONSE_BYTES = 1024 * 1024; +const PROBE_MAX_TOKENS = 256; +const DEFAULT_CONTEXT = 8192; +const DEFAULT_MAX_TOKENS = 2048; +const DEFAULT_HTTP_PORT = '80'; +const PROBE_VALUE = 'hive_mlx_tool_check'; +const COMPAT = Object.freeze({ + supportsStore: false, + supportsDeveloperRole: false, + supportsReasoningEffort: false, + maxTokensField: 'max_tokens', +}); + +function endpointURL(raw) { + let url; + try { url = new URL(raw); } catch (_) { throw new Error('MLX endpoint must be http://127.0.0.1:/v1'); } + // Literal loopback only: no DNS resolution, credentials, redirects or public + // listeners. Docker Desktop host networking keeps this exact host boundary. + if (url.protocol !== 'http:' || !['127.0.0.1', '[::1]'].includes(url.hostname) || + url.username || url.password || url.search || url.hash || !/^\/v1\/?$/.test(url.pathname)) { + throw new Error('MLX requires a literal loopback HTTP endpoint ending in /v1; never expose MLX-LM publicly'); + } + return url.href.replace(/\/$/, ''); +} + +function validatePlatform(info) { + if (info.platform !== 'darwin' || info.arch !== 'arm64') { + throw new Error('Apple MLX requires a native arm64 process on an Apple Silicon Mac; Intel, Rosetta and Linux hosts are unsupported'); + } + if (Number(String(info.macos).split('.')[0]) < 14 || !/^\d+\./.test(info.macos)) { + throw new Error('Apple MLX requires macOS 14 or newer'); + } + if (info.pythonArch !== 'arm64' || info.pythonPlatform !== 'darwin') { + throw new Error('MLX Python must run natively on Apple Silicon, not under Rosetta; select it with HIVE_MLX_PYTHON'); + } + const [major, minor] = info.pythonVersion || []; + if (!(major > 3 || (major === 3 && minor >= 10))) { + throw new Error('MLX requires native Python >=3.10; select your virtualenv Python with HIVE_MLX_PYTHON'); + } + if (!info.mlx || !info.mlxLM) { + throw new Error('MLX/MLX-LM is missing in HIVE_MLX_PYTHON; install mlx-lm in your own virtualenv (no global pip install)'); + } + return info; +} + +function hostInfo(env = process.env) { + if (process.platform !== 'darwin' || process.arch !== 'arm64') { + throw new Error('Apple MLX requires a native arm64 process on an Apple Silicon Mac; Intel, Rosetta and Linux hosts are unsupported'); + } + let python; + try { + // Metadata only: importing mlx can initialize the GPU. + python = JSON.parse(execFileSync(env.HIVE_MLX_PYTHON || 'python3', ['-c', [ + 'import sys, platform, json, importlib.metadata as m', + 'def version(name):', + ' try: return m.version(name)', + ' except m.PackageNotFoundError: return None', + 'print(json.dumps(dict(pythonArch=platform.machine(), pythonPlatform=sys.platform, pythonVersion=list(sys.version_info[:2]), mlx=version("mlx"), mlxLM=version("mlx-lm"))))', + ].join('\n')], { encoding: 'utf8', timeout: HTTP_TIMEOUT_MS, stdio: ['ignore', 'pipe', 'pipe'] })); + } catch (_) { + throw new Error('Cannot inspect MLX Python; set HIVE_MLX_PYTHON to your native Python >=3.10 virtualenv executable'); + } + return validatePlatform({ + ...python, + platform: process.platform, + arch: process.arch, + macos: process.platform === 'darwin' + ? execFileSync('sw_vers', ['-productVersion'], { encoding: 'utf8', timeout: HTTP_TIMEOUT_MS }).trim() : '', + }); +} + +async function request(endpoint, route, body, timeout = HTTP_TIMEOUT_MS, fetcher = fetch) { + const url = endpointURL(endpoint); + try { + const response = await fetcher(`${url}/${route}`, { + method: body ? 'POST' : 'GET', + headers: body ? { 'Content-Type': 'application/json' } : {}, + ...(body ? { body: JSON.stringify(body) } : {}), + signal: AbortSignal.timeout(timeout), + redirect: 'error', + }); + if (!response.ok) throw new Error(`HTTP ${response.status}`); + const reader = response.body.getReader(); + const chunks = []; + let size = 0; + try { + while (true) { + const { done, value } = await reader.read(); + if (done) break; + size += value.length; + if (size > MAX_RESPONSE_BYTES) throw new Error('response exceeds safety limit'); + chunks.push(Buffer.from(value)); + } + } finally { await reader.cancel(); } + return Buffer.concat(chunks).toString('utf8'); + } catch (error) { + throw new Error(`MLX local endpoint request failed (${error.name === 'TimeoutError' ? 'timed out' : error.message}); start your MLX-LM server and check Docker Desktop host networking if containerized`); + } +} + +async function availableModels(endpoint, fetcher) { + const body = JSON.parse(await request(endpoint, 'models', null, HTTP_TIMEOUT_MS, fetcher)); + if (!Array.isArray(body.data) || !body.data.every(model => typeof model.id === 'string')) { + throw new Error('MLX /v1/models returned an invalid model list'); + } + return body.data.map(model => model.id); +} + +function parseStream(text) { + const calls = new Map(); + let content = '', fingerprint = '', finish = '', done = false; + for (const line of text.split(/\r?\n/)) { + if (!line.startsWith('data:')) continue; + const data = line.slice(5).trim(); + if (data === '[DONE]') { done = true; continue; } + const chunk = JSON.parse(data); + if (chunk.error) throw new Error('MLX returned a streaming error'); + fingerprint = chunk.system_fingerprint || fingerprint; + for (const choice of chunk.choices || []) { + finish = choice.finish_reason || finish; + content += choice.delta?.content || ''; + for (const call of choice.delta?.tool_calls || []) { + if (!Number.isInteger(call.index)) throw new Error('MLX tool-call stream has no index'); + const prior = calls.get(call.index) || { id: '', type: 'function', function: { name: '', arguments: '' } }; + prior.id += call.id || ''; + prior.function.name += call.function?.name || ''; + prior.function.arguments += call.function?.arguments || ''; + calls.set(call.index, prior); + } + } + } + if (!done) throw new Error('MLX stream ended without [DONE]'); + return { calls: [...calls.values()], content, fingerprint, finish }; +} + +async function verifyTools(endpoint, model, fetcher) { + const tools = [{ + type: 'function', + function: { + name: 'hive_mlx_check', + description: 'Echo a value to verify structured tool calling. Call this tool exactly once.', + parameters: { type: 'object', properties: { value: { type: 'string' } }, required: ['value'], additionalProperties: false }, + }, + }]; + const messages = [{ role: 'user', content: `Call hive_mlx_check with value "${PROBE_VALUE}". Do not answer in prose.` }]; + const complete = async () => parseStream(await request(endpoint, 'chat/completions', { + model, messages, tools, stream: true, max_tokens: PROBE_MAX_TOKENS, temperature: 0, + }, PROBE_TIMEOUT_MS, fetcher)); + const first = await complete(); + const call = first.calls[0]; + if (first.finish !== 'tool_calls' || first.calls.length !== 1 || !call?.id || + call.function.name !== 'hive_mlx_check' || JSON.parse(call.function.arguments).value !== PROBE_VALUE) { + throw new Error('Selected MLX model/runtime failed the streaming tool-call check; use a model with a supported MLX-LM tool parser/chat template'); + } + messages.push({ role: 'assistant', content: first.content || null, tool_calls: first.calls }); + messages.push({ role: 'tool', tool_call_id: call.id, content: PROBE_VALUE }); + messages.push({ role: 'user', content: 'Return the tool result verbatim, without calling any more tools.' }); + const second = await complete(); + if (second.calls.length || second.finish !== 'stop' || second.content.trim() !== PROBE_VALUE) { + throw new Error('Selected MLX model/runtime failed the tool-result round trip'); + } + return first.fingerprint; +} + +function agentDir(env = process.env) { + return env.PI_CODING_AGENT_DIR || path.join(env.HOME, '.pi', 'agent'); +} + +function readJSON(file) { + return JSON.parse(fs.readFileSync(file, 'utf8')); +} + +function digest(provider) { + return createHash('sha256').update(JSON.stringify(provider)).digest('hex'); +} + +function tokenBudget(raw, fallback) { + const value = Number(raw || fallback); + if (!Number.isSafeInteger(value) || value <= 0) throw new Error('MLX context/output token limits must be positive integers'); + return value; +} + +function serve(model, env = process.env, inspectHost = hostInfo, launch = execFileSync) { + const selection = parsePiModelSelection(`mlx/${model || ''}`); + if (!selection.valid || model === 'default_model') throw new Error('Choose an explicit, already-downloaded MLX model ID or absolute path'); + inspectHost(env); + if (path.isAbsolute(model)) { + try { + if (!fs.statSync(model).isDirectory()) throw new Error('not a directory'); + } catch (_) { throw new Error('MLX model directory is missing; download the model yourself before running contribute-mlx-serve'); } + } + const endpoint = new URL(endpointURL(env.HIVE_MLX_ENDPOINT || DEFAULT_ENDPOINT)); + launch(env.HIVE_MLX_PYTHON || 'python3', [ + '-m', 'mlx_lm.server', '--model', model, + '--host', endpoint.hostname.replace(/^\[|\]$/g, ''), + '--port', endpoint.port || DEFAULT_HTTP_PORT, + ], { env: { ...env, HF_HUB_OFFLINE: '1' }, stdio: 'inherit' }); +} + +async function configure(model, env = process.env, fetcher, inspectHost = hostInfo) { + if (typeof model !== 'string' || !model) throw new Error('An explicit MLX model ID or absolute path is required'); + const selection = parsePiModelSelection(`mlx/${model}`); + if (!selection.valid || model === 'default_model') throw new Error('Choose an explicit MLX model ID or absolute path without whitespace, not default_model'); + const info = inspectHost(env); + const endpoint = endpointURL(env.HIVE_MLX_ENDPOINT || DEFAULT_ENDPOINT); + if (!(await availableModels(endpoint, fetcher)).includes(model)) { + throw new Error('MLX model is not listed by /v1/models; download it yourself or start the server with its local absolute path first'); + } + const contextWindow = tokenBudget(env.HIVE_MLX_CONTEXT_WINDOW, DEFAULT_CONTEXT); + const maxTokens = tokenBudget(env.HIVE_MLX_MAX_TOKENS, DEFAULT_MAX_TOKENS); + if (maxTokens >= contextWindow) throw new Error('HIVE_MLX_MAX_TOKENS must be smaller than HIVE_MLX_CONTEXT_WINDOW'); + const dir = agentDir(env); + const file = path.join(dir, 'models.json'); + const models = fs.existsSync(file) ? readJSON(file) : { providers: {} }; + if (!models || typeof models !== 'object' || Array.isArray(models) || + (models.providers !== undefined && (!models.providers || typeof models.providers !== 'object' || Array.isArray(models.providers)))) { + throw new Error('Refusing to overwrite malformed Pi models.json'); + } + models.providers ||= {}; + // Deliberately opt-in: the configure CLI requires --verify-tools. Only this + // explicit operation runs two bounded inference requests, never startup. + const fingerprint = await verifyTools(endpoint, model, fetcher); + if (!fingerprint.startsWith(`${info.mlxLM}-${info.mlx}-`)) { + throw new Error('Endpoint fingerprint does not match your MLX-LM/MLX environment; select the server virtualenv with HIVE_MLX_PYTHON'); + } + const provider = { + baseUrl: endpoint, api: 'hive-mlx', apiKey: 'mlx-local', compat: COMPAT, + models: [{ id: model, name: model, reasoning: false, input: ['text'], contextWindow, maxTokens, + cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 } }], + }; + models.providers.mlx = provider; + fs.mkdirSync(dir, { recursive: true, mode: 0o700 }); + // A stale receipt cannot authorize a half-written configuration. + fs.writeFileSync(file, `${JSON.stringify(models, null, 2)}\n`, { mode: 0o600 }); + fs.chmodSync(file, 0o600); + fs.writeFileSync(path.join(dir, 'hive-mlx.json'), `${JSON.stringify({ + platform: 'darwin', arch: 'arm64', model, providerDigest: digest(provider), + mlx: info.mlx, mlxLM: info.mlxLM, fingerprint, verifiedAt: new Date().toISOString(), + }, null, 2)}\n`, { mode: 0o600 }); + fs.chmodSync(path.join(dir, 'hive-mlx.json'), 0o600); + return selection.canonical; +} + +function configuration(selection, env = process.env) { + if (!selection.valid || selection.provider !== 'mlx') throw new Error('MLX selection must use mlx/'); + let provider, receipt; + try { + provider = readJSON(path.join(agentDir(env), 'models.json')).providers.mlx; + receipt = readJSON(path.join(agentDir(env), 'hive-mlx.json')); + } catch (_) { throw new Error('MLX is not configured; run just contribute-mlx-setup --verify-tools on the Mac host first'); } + if (receipt.platform !== 'darwin' || receipt.arch !== 'arm64' || receipt.model !== selection.model || + receipt.providerDigest !== digest(provider)) { + throw new Error('MLX configuration changed or lacks a matching tool-check receipt; rerun contribute-mlx-setup --verify-tools'); + } + endpointURL(provider.baseUrl); + return provider; +} + +async function check(raw, env = process.env, fetcher, inspectHost = hostInfo) { + const selection = parsePiModelSelection(raw); + const provider = configuration(selection, env); + if (inspectHost) inspectHost(env); + if (!(await availableModels(provider.baseUrl, fetcher)).includes(selection.model)) { + throw new Error('Configured MLX model is missing from /v1/models; restore it and rerun contribute-mlx-setup --verify-tools'); + } +} + +function checkRuntime(raw, env = process.env, run = execFileSync) { + if (!raw.startsWith('mlx/')) return; + try { + run(process.execPath, [__filename, 'check', raw, process.platform === 'darwin' ? '--host' : '--endpoint-only'], { + env, encoding: 'utf8', timeout: HTTP_TIMEOUT_MS * 2, stdio: ['ignore', 'pipe', 'pipe'], + }); + } catch (error) { + throw new Error(String(error.stderr || 'MLX preflight failed; check the local server and container host networking').trim()); + } +} + +module.exports = { endpointURL, validatePlatform, hostInfo, availableModels, parseStream, verifyTools, configure, configuration, check, checkRuntime, serve, DEFAULT_ENDPOINT }; + +if (require.main === module) { + (async () => { + const [command, model, flag] = process.argv.slice(2); + if (command === 'configure' && flag === '--verify-tools') { + const selected = await configure(model); + console.log(`MLX streaming tool round trip verified. Select AGENT_BACKEND=pi AGENT_MODEL=${selected}`); + } else if (command === 'serve') { + serve(model); + } else if (command === 'check') { + await check(model, process.env, undefined, flag === '--endpoint-only' ? null : hostInfo); + console.log('MLX endpoint/model ready; coding execution is provided by Pi, not MLX-LM'); + } else { + throw new Error('Usage: mlx-backend.js configure --verify-tools (explicitly runs two bounded inference requests), serve (foreground, offline, loopback), or check mlx/'); + } + })().catch(error => { console.error(error.message); process.exitCode = 1; }); +} diff --git a/bin/mlx-backend.test.js b/bin/mlx-backend.test.js new file mode 100644 index 0000000000..9cc6f58ded --- /dev/null +++ b/bin/mlx-backend.test.js @@ -0,0 +1,293 @@ +'use strict'; + +const assert = require('node:assert/strict'); +const { test } = require('node:test'); +const fs = require('node:fs'); +const path = require('node:path'); +const http = require('node:http'); +const { randomUUID } = require('node:crypto'); +const { execFileSync } = require('node:child_process'); +const mlx = require('./mlx-backend.js'); +const pi = require('./pi-backend.js'); +const extension = require('./mlx-pi-extension.js'); + +const MODEL = 'mlx-community/tool-coder-4bit'; +const FINGERPRINT = '0.31.0-0.31.0-macOS-test-arm64'; +const HOST = { + platform: 'darwin', arch: 'arm64', macos: '14.0', + pythonArch: 'arm64', pythonPlatform: 'darwin', pythonVersion: [3, 10], + mlx: '0.31.0', mlxLM: '0.31.0', +}; +const CALL = { index: 0, id: 'check-1', type: 'function', function: { name: 'hive_mlx_check', arguments: '{"value":"hive_mlx_tool_check"}' } }; + +function stream(delta, finish = 'stop', fingerprint = FINGERPRINT) { + return `data: ${JSON.stringify({ system_fingerprint: fingerprint, choices: [{ delta, finish_reason: finish }] })}\n\ndata: [DONE]\n\n`; +} + +function fixture(t) { + const dir = path.join(__dirname, `.mlx-fixture-${randomUUID()}`); + fs.mkdirSync(dir); + t.after(() => fs.rmSync(dir, { recursive: true, force: true })); + return { HOME: dir, PI_CODING_AGENT_DIR: path.join(dir, '.pi', 'agent') }; +} + +function fakeServer(options = {}) { + const calls = []; + return { + calls, + fetch: async (url, init) => { + calls.push({ url, init }); + assert.equal(init.redirect, 'error'); + if (init.method === 'GET') { + return new Response(JSON.stringify({ data: (options.models || [MODEL]).map(id => ({ id })) })); + } + const request = JSON.parse(init.body); + assert.equal(request.model, options.model || MODEL); + assert.equal(request.stream, true); + assert.equal(request.max_tokens, 256); + assert.equal(request.tools[0].function.name, 'hive_mlx_check'); + if (request.messages.length === 1) { + return new Response(options.prose + ? stream({ content: 'I would call the tool' }) + : stream({ tool_calls: [CALL] }, 'tool_calls', options.fingerprint || FINGERPRINT)); + } + assert.equal(request.messages[1].tool_calls[0].id, 'check-1'); + assert.equal(request.messages[2].role, 'tool'); + assert.equal(request.messages[2].tool_call_id, 'check-1'); + assert.equal(request.messages[2].content, 'hive_mlx_tool_check'); + return new Response(stream({ content: options.badRoundTrip ? 'no' : 'hive_mlx_tool_check' })); + }, + }; +} + +test('Apple Silicon/native Python/macOS compatibility is explicit and optional', () => { + assert.equal(mlx.validatePlatform(HOST), HOST); + for (const [override, error] of [ + [{ platform: 'linux' }, /Apple Silicon/], + [{ arch: 'x64' }, /Rosetta/], + [{ macos: '13.7' }, /macOS 14/], + [{ macos: '' }, /macOS 14/], + [{ pythonArch: 'x86_64' }, /natively/], + [{ pythonPlatform: 'linux' }, /natively/], + [{ pythonVersion: [3, 9] }, /Python >=3.10/], + [{ mlxLM: null }, /virtualenv/], + [{ mlx: null }, /virtualenv/], + ]) assert.throws(() => mlx.validatePlatform({ ...HOST, ...override }), error); + // Other Pi providers never inspect a Python environment or an endpoint. + assert.doesNotThrow(() => mlx.checkRuntime('anthropic/claude-sonnet-4-6', {})); + assert.equal(pi.parsePiModelSelection('openai/gpt-4o').canonical, 'openai/gpt-4o'); + assert.equal(pi.parsePiModelSelection('openai//absolute').valid, false); + assert.equal(pi.parsePiModelSelection('mlx//Users/contributor/models/coder').valid, true); + assert.equal(pi.parsePiModelSelection('mlx//Users/a b/coder').valid, false); +}); + +test('endpoint is strictly loopback; credentials, DNS, paths and hosted fallbacks are refused', () => { + assert.equal(mlx.endpointURL('http://127.0.0.1:8080/v1/'), mlx.DEFAULT_ENDPOINT); + assert.equal(mlx.endpointURL('http://[::1]:8080/v1'), 'http://[::1]:8080/v1'); + for (const endpoint of [ + 'https://api.openai.com/v1', 'http://0.0.0.0:8080/v1', + 'http://localhost:8080/v1', 'http://host.docker.internal:8080/v1', + 'http://secret@127.0.0.1:8080/v1', 'http://127.0.0.1/v1?key=x', + 'http://127.0.0.1/v1#x', 'http://127.0.0.1/other', 'invalid', + ]) assert.throws(() => mlx.endpointURL(endpoint), /endpoint/); +}); + +test('explicit setup preserves other providers and persists verified Pi configuration', async t => { + const env = fixture(t); + fs.mkdirSync(env.PI_CODING_AGENT_DIR, { recursive: true }); + const original = { providers: { anthropic: { apiKey: 'do-not-copy-me' } }, other: 'preserved' }; + fs.writeFileSync(path.join(env.PI_CODING_AGENT_DIR, 'models.json'), JSON.stringify(original)); + const server = fakeServer(); + assert.equal(await mlx.configure(MODEL, env, server.fetch, () => HOST), `mlx/${MODEL}`); + assert.equal(server.calls.length, 3); + const config = JSON.parse(fs.readFileSync(path.join(env.PI_CODING_AGENT_DIR, 'models.json'))); + assert.deepEqual(config.providers.anthropic, original.providers.anthropic); + assert.equal(config.other, 'preserved'); + assert.equal(config.providers.mlx.api, 'hive-mlx'); + assert.equal(config.providers.mlx.compat.maxTokensField, 'max_tokens'); + assert.equal(config.providers.mlx.models[0].id, MODEL); + assert.equal(config.providers.mlx.models[0].contextWindow, 8192); + assert.equal(fs.statSync(path.join(env.PI_CODING_AGENT_DIR, 'models.json')).mode & 0o777, 0o600); + assert.equal(pi.piCredentialConfiguration(pi.parsePiModelSelection(`mlx/${MODEL}`), env), 'configured_unverified'); + await mlx.check(`mlx/${MODEL}`, env, server.fetch, null); + assert.equal(server.calls.length, 4, 'startup makes only a model-list request, never inference'); + pi.narrowPiStage(path.join(env.HOME, '.pi'), pi.parsePiModelSelection(`mlx/${MODEL}`)); + assert.deepEqual(Object.keys(JSON.parse(fs.readFileSync(path.join(env.PI_CODING_AGENT_DIR, 'models.json'))).providers), ['mlx']); + await mlx.check(`mlx/${MODEL}`, env, server.fetch, null); +}); + +test('setup rejects missing models, prose-only models, broken tools and wrong runtime without writing config', async t => { + for (const [options, error] of [ + [{ models: ['other'] }, /not listed/], + [{ prose: true }, /streaming tool-call/], + [{ badRoundTrip: true }, /tool-result/], + [{ fingerprint: 'not-mlx' }, /fingerprint/], + ]) { + const env = fixture(t); + await assert.rejects(mlx.configure(MODEL, env, fakeServer(options).fetch, () => HOST), error); + assert.equal(fs.existsSync(path.join(env.PI_CODING_AGENT_DIR, 'models.json')), false); + } +}); + +test('startup fails closed for unconfigured, tampered, missing and unreachable models', async t => { + const env = fixture(t); + await assert.rejects(mlx.check(`mlx/${MODEL}`, env, fakeServer().fetch, null), /not configured/); + await mlx.configure(MODEL, env, fakeServer().fetch, () => HOST); + await assert.rejects(mlx.check(`mlx/${MODEL}`, env, fakeServer({ models: [] }).fetch, null), /missing/); + await assert.rejects(mlx.check(`mlx/${MODEL}`, env, async () => { throw new Error('connection refused'); }, null), /local endpoint request failed/); + const configFile = path.join(env.PI_CODING_AGENT_DIR, 'models.json'); + const config = JSON.parse(fs.readFileSync(configFile)); + config.providers.mlx.baseUrl = 'https://api.openai.com/v1'; + fs.writeFileSync(configFile, JSON.stringify(config)); + await assert.rejects(mlx.check(`mlx/${MODEL}`, env, fakeServer().fetch, null), /configuration changed/); +}); + +test('stream parser assembles fragmented tool arguments and rejects truncated/error streams', () => { + const fragments = [ + { index: 0, id: 'check-1', function: { name: 'hive_mlx_check', arguments: '{"value":' } }, + { index: 0, function: { arguments: '"hive_mlx_tool_check"}' } }, + ].map(call => stream({ tool_calls: [call] }, 'tool_calls').replace('data: [DONE]\n\n', '')).join(''); + const parsed = mlx.parseStream(`: keepalive\n\n${fragments}data: [DONE]\n\n`); + assert.equal(parsed.calls[0].function.arguments, CALL.function.arguments); + assert.throws(() => mlx.parseStream(fragments), /without \[DONE\]/); + assert.throws(() => mlx.parseStream('data: {"error":"bad"}\n\n'), /streaming error/); +}); + +test('HTTP seam handles actual local streaming responses and refuses redirects', async t => { + const server = http.createServer((req, res) => { + if (req.url === '/v1/models') { + res.writeHead(200, { 'Content-Type': 'application/json' }); + res.end(JSON.stringify({ data: [{ id: MODEL }] })); + } else { + res.writeHead(302, { Location: 'https://api.openai.com/v1/models' }); + res.end(); + } + }); + await new Promise(resolve => server.listen(0, '127.0.0.1', resolve)); + t.after(() => new Promise(resolve => server.close(resolve))); + const endpoint = `http://127.0.0.1:${server.address().port}/v1`; + assert.deepEqual(await mlx.availableModels(endpoint), [MODEL]); + await assert.rejects(mlx.verifyTools(endpoint, MODEL), /local endpoint request failed/); +}); + +test('model paths and token budgets are contributor owned and no default model is selected', async t => { + const env = fixture(t); + for (const model of ['', 'default_model', 'model;touch-elsewhere']) { + await assert.rejects(mlx.configure(model, env, fakeServer().fetch, () => HOST)); + } + await assert.rejects(mlx.configure(MODEL, { ...env, HIVE_MLX_CONTEXT_WINDOW: 'bad' }, fakeServer().fetch, () => HOST), /positive integers/); + await assert.rejects(mlx.configure(MODEL, { ...env, HIVE_MLX_MAX_TOKENS: '8192' }, fakeServer().fetch, () => HOST), /smaller/); + const model = '/Users/contributor/models/coder'; + const server = fakeServer({ model, models: [model] }); + assert.equal(await mlx.configure(model, env, server.fetch, () => HOST), `mlx/${model}`); +}); + +test('runtime preflight is a bounded subprocess and reports failures without fallback', () => { + const env = { HOME: '/contributor' }; + const calls = []; + mlx.checkRuntime(`mlx/${MODEL}`, env, (...args) => { calls.push(args); }); + assert.equal(calls.length, 1); + assert.equal(calls[0][0], process.execPath); + assert.deepEqual(calls[0][1].slice(1), ['check', `mlx/${MODEL}`, process.platform === 'darwin' ? '--host' : '--endpoint-only']); + assert.equal(calls[0][2].env, env); + assert.equal(calls[0][2].timeout, 20000); + const error = Object.assign(new Error('failed'), { stderr: Buffer.from('MLX local endpoint unreachable') }); + assert.throws(() => mlx.checkRuntime(`mlx/${MODEL}`, env, () => { throw error; }), /endpoint unreachable/); +}); + +test('real Pi provider delegate forces loopback-only fetch and preserves tools and cancellation', async t => { + const env = fixture(t); + env.AGENT_MODEL = `mlx/${MODEL}`; + await mlx.configure(MODEL, env, fakeServer().fetch, () => HOST); + const delegateCalls = []; + const fetchCalls = []; + let registered; + const streamResult = { marker: 'Pi stream and tool executor' }; + extension.registerMlx({ registerProvider(name, config) { + assert.equal(name, 'mlx'); + registered = config; + } }, { streamSimple(...args) { delegateCalls.push(args); return streamResult; } }, env, + async (...args) => { fetchCalls.push(args); return new Response('ok'); }); + assert.equal(registered.api, 'hive-mlx'); + const model = { provider: 'mlx', id: MODEL, baseUrl: mlx.DEFAULT_ENDPOINT, api: 'hive-mlx' }; + const context = { messages: [{ role: 'toolResult', content: [{ type: 'text', text: 'edited file' }] }] }; + const controller = new AbortController(); + const options = { signal: controller.signal, onPayload() {}, fetch() { throw new Error('must not override guard'); } }; + assert.equal(registered.streamSimple(model, context, options), streamResult); + const [effectiveModel, actualContext, actualOptions] = delegateCalls[0]; + assert.equal(effectiveModel.api, 'openai-completions'); + assert.equal(actualContext, context, 'Pi retains the full tool transcript'); + assert.equal(actualOptions.signal, controller.signal); + assert.equal(actualOptions.onPayload, options.onPayload); + await actualOptions.fetch(`${mlx.DEFAULT_ENDPOINT}/chat/completions`, { redirect: 'follow', method: 'POST' }); + assert.equal(fetchCalls[0][1].redirect, 'error'); + assert.throws(() => actualOptions.fetch('https://api.openai.com/v1/chat/completions'), /loopback/); + assert.throws(() => registered.streamSimple({ ...model, id: 'another' }, context, options), /model changed/); +}); + +test('Pi inference transport rejects redirects after successful setup', async t => { + const server = http.createServer((req, res) => { + res.writeHead(307, { Location: 'https://api.openai.com/v1/chat/completions' }); + res.end(); + }); + + test('explicit serve recipe uses native Python, loopback and offline weights without changing RAM settings', t => { + const env = fixture(t); + const model = path.join(env.HOME, 'model'); + fs.mkdirSync(model); + const calls = []; + mlx.serve(model, { ...env, HIVE_MLX_PYTHON: '/chosen/python', HIVE_MLX_ENDPOINT: 'http://127.0.0.1:8081/v1' }, + () => HOST, (...args) => calls.push(args)); + assert.equal(calls[0][0], '/chosen/python'); + assert.deepEqual(calls[0][1], ['-m', 'mlx_lm.server', '--model', model, '--host', '127.0.0.1', '--port', '8081']); + assert.equal(calls[0][2].env.HF_HUB_OFFLINE, '1'); + assert.equal(calls[0][2].stdio, 'inherit'); + assert.throws(() => mlx.serve(path.join(model, 'missing'), env, () => HOST, () => assert.fail('must not launch')), /directory is missing/); + assert.throws(() => mlx.serve(model, { ...env, HIVE_MLX_ENDPOINT: 'http://0.0.0.0:8080/v1' }, () => HOST), /loopback/); + assert.throws(() => mlx.serve(model, env, () => { throw new Error('unsupported Rosetta Python'); }, () => assert.fail('must not launch')), /Rosetta/); + }); + + test('MLX just launcher remains a Pi wrapper with explicit model/runtime refusal', () => { + const recipes = fs.readFileSync(path.join(__dirname, '..', 'Justfile'), 'utf8'); + const launcher = recipes.split('contribute-mlx mode="docker":')[1].split('\n\n')[0]; + assert.match(launcher, /\$\{AGENT_MODEL:-\}" != mlx\/\*/); + assert.match(launcher, /contribute-hive pi "\$1"/); + assert.match(launcher, /export HIVE_CONTAINER_RUNTIME=docker/); + assert.match(launcher, /Kubernetes cannot reach Mac loopback/); + assert.match(recipes, /contribute-mlx-serve model:\n node bin\/mlx-backend\.js serve "\$1"/); + }); + + test('MLX launcher preserves explicit model across both saved-profile loads without changing generic Pi defaults', t => { + const env = fixture(t); + const config = path.join(env.HOME, 'contributor.env'); + fs.writeFileSync(config, 'AGENT_MODEL=anthropic/saved-hosted-model\nHIVE_CONTAINER_RUNTIME=podman\n'); + const recipes = fs.readFileSync(path.join(__dirname, '..', 'Justfile'), 'utf8'); + const launcher = recipes.split('contribute-mlx mode="docker":')[1].split('\n\n')[0] + .replaceAll('{{config_dir}}', env.HOME) + .replace('{{justfile_directory()}}', path.join(__dirname, '..')); + const guard = recipes.split('# MLX-only launch override:')[1].split('# End MLX-only launch override.')[0]; + const nested = guard.slice(guard.indexOf('\n')); + const script = `just() { + local _MLX_LAUNCH_MODEL="\${HIVE_MLX_LAUNCH_MODEL:-}" + source "${config}" + BACKEND=pi + ${nested} + printf '%s' "$AGENT_MODEL" + }\n${launcher}`; + const result = execFileSync('bash', ['-s', '--', 'docker'], { + input: script, encoding: 'utf8', + env: { ...process.env, ...env, AGENT_MODEL: `mlx/${MODEL}`, HIVE_CONTAINER_RUNTIME: 'docker' }, + }); + assert.equal(result, `mlx/${MODEL}`); + const ordinary = execFileSync('bash', ['-s'], { + input: `AGENT_MODEL=anthropic/saved-hosted-model; BACKEND=pi; _MLX_LAUNCH_MODEL='';\n${nested}\nprintf '%s' "$AGENT_MODEL"`, + encoding: 'utf8', + }); + assert.equal(ordinary, 'anthropic/saved-hosted-model'); + }); + await new Promise(resolve => server.listen(0, '127.0.0.1', resolve)); + t.after(() => new Promise(resolve => server.close(resolve))); + const endpoint = `http://127.0.0.1:${server.address().port}/v1`; + const guarded = extension.localFetch(endpoint); + await assert.rejects(guarded(`${endpoint}/chat/completions`, { method: 'POST', body: 'private task' })); +}); diff --git a/bin/mlx-pi-extension.js b/bin/mlx-pi-extension.js new file mode 100644 index 0000000000..b2a99b480a --- /dev/null +++ b/bin/mlx-pi-extension.js @@ -0,0 +1,48 @@ +'use strict'; + +const { configuration, endpointURL } = require('./mlx-backend.js'); +const { parsePiModelSelection } = require('./pi-backend.js'); + +function localFetch(endpoint, fetcher = globalThis.fetch) { + const allowed = `${endpointURL(endpoint)}/chat/completions`; + return (input, init) => { + const url = typeof input === 'string' || input instanceof URL ? String(input) : input.url; + if (url !== allowed) throw new Error('MLX inference request left its configured loopback endpoint'); + // Apply this to Pi's REAL inference transport, not just the setup probe. + // In particular a 307/308 must never forward task prompts to another host. + return fetcher(input, { ...init, redirect: 'error' }); + }; +} + +function registerMlx(pi, api, env = process.env, fetcher = globalThis.fetch) { + const selection = parsePiModelSelection(env.AGENT_MODEL || ''); + const provider = configuration(selection, env); + const guardedFetch = localFetch(provider.baseUrl, fetcher); + pi.registerProvider('mlx', { + ...provider, + streamSimple(model, context, options) { + if (model.provider !== 'mlx' || model.id !== selection.model || model.baseUrl !== provider.baseUrl) { + throw new Error('MLX model changed; reconfigure and restart the contributor relay'); + } + // Reuse Pi's maintained OpenAI message/tool conversion, stream decoder, + // usage accounting and AbortSignal handling. Do not build a new executor. + return api.streamSimple({ ...model, api: 'openai-completions' }, context, { + ...options, fetch: guardedFetch, + }); + }, + }); +} + +module.exports = function mlxExtension(pi) { + // Pi 1.4.0 resolves this through its extension compatibility entrypoint, + // including in standalone distributions. No global Pi dependency is needed + // by ClankeR's relay or its test runner. + const { openAICompletionsApi, PI_AI_VERSION } = require('@earendil-works/pi-ai'); + const [major, minor] = String(PI_AI_VERSION || '').split('.').map(Number); + if (typeof openAICompletionsApi !== 'function' || !(major > 1 || (major === 1 && minor >= 4))) { + throw new Error('ClankeR MLX requires Pi >=1.4.0 with custom fetch transport support; update your Pi installation'); + } + registerMlx(pi, openAICompletionsApi()); +}; +module.exports.localFetch = localFetch; +module.exports.registerMlx = registerMlx; diff --git a/bin/pi-backend.js b/bin/pi-backend.js index a8741b383a..9966add909 100644 --- a/bin/pi-backend.js +++ b/bin/pi-backend.js @@ -66,7 +66,8 @@ function parsePiModelSelection(raw) { // This token is also used by the interactive shell launcher. Restrict it to // model-ID punctuation so a contributor preference can never become shell // syntax while retaining paths (OpenRouter), tags (Ollama), and revisions. - if (!/^[A-Za-z0-9][A-Za-z0-9._/+:@~-]*$/.test(model)) { + const modelPattern = provider === 'mlx' ? /^(?:[A-Za-z0-9]|\/)[A-Za-z0-9._/+:@~-]*$/ : /^[A-Za-z0-9][A-Za-z0-9._/+:@~-]*$/; + if (!modelPattern.test(model)) { return { valid: false, state: 'invalid', error: 'invalid Pi model in AGENT_MODEL' }; } return { valid: true, state: 'configured', provider, model, canonical: raw }; diff --git a/changelog.d/added-clanker-mlx.md b/changelog.d/added-clanker-mlx.md new file mode 100644 index 0000000000..ea4e4f27f9 --- /dev/null +++ b/changelog.d/added-clanker-mlx.md @@ -0,0 +1 @@ +- ClankeR contributors can select Apple MLX on `/contribute` and use dedicated `just` setup/serve/launch recipes for user-managed MLX-LM inference through Pi on supported Apple Silicon Macs, with loopback-only configuration, explicit streaming tool-call verification, fail-closed checks, and public integration/setup documentation. diff --git a/docs/backend-setup.md b/docs/backend-setup.md index 43d1593305..8d56d018b6 100644 --- a/docs/backend-setup.md +++ b/docs/backend-setup.md @@ -12,6 +12,7 @@ Hive validates backend names in `src/pkg/config` and launches CLIs in `src/crux/ | `gemini` | `gemini` | Install Gemini CLI and configure its normal auth/API key. | Supported by the server-side manager; Hive launches `gemini` and passes `--model` when a model is configured. | | `goose` | `goose` | Install [Goose](https://github.com/aaif-goose/goose) from its canonical upstream and configure provider/model (`GOOSE_PROVIDER`, `GOOSE_MODEL`, or `goose configure`). | Hive launches `goose run -s` and appends `--model` when set. | | `pi` | `goose` in the Go manager; `pi` in contributor scripts | Contributor mode requires `AGENT_MODEL=provider/model` plus that provider's official credential variable or `~/.pi/agent/auth.json`. In the server-side manager, `backendBinary("pi")` maps to Goose. | Contributor Pi supports interactive and headless (`--print --mode json`) delivery. No generic Pi key/provider variable exists. | +| `pi` + Apple MLX | `pi` in contributor scripts only | `/contribute` offers **Apple MLX**, mapped to Pi with `AGENT_MODEL=mlx/`. Run `just contribute-mlx-serve `, explicitly verify via `just contribute-mlx-setup --verify-tools`, register with `just contribute-setup pi`, then `just contribute-mlx`. | Apple Silicon, macOS 14+, native Python 3.10+, Pi 1.4.0+, tool-capable model and Docker Desktop host networking; MLX-LM runs on the Mac. Not a hosted agent backend or a standalone coding CLI. [Installation, RAM budget and troubleshooting](../src/docs/contributor-relay.md#apple-mlx-local-inference). | | `pi` + Kiro | `goose` in the Go manager; `pi` in contributor scripts | Set `KIRO_API_KEY` and use the Pi Kiro provider model id shape, for example `AGENT_MODEL=kiro-api-key/claude-opus-5:high`. Hive forwards `KIRO_API_KEY` into contributor containers and the dashboard's `pi` model picker includes common `kiro-api-key/*` IDs as a non-authoritative fallback. | This is the supported Kiro path for now instead of a first-class `kiro-cli` backend: Kiro's stable unattended/trust/login CLI contract is not verified in Hive, while `pi` + `pi-kiro-api` is already the adopter-proven path. Quota headroom remains separate from the `anthropic` pool until the Kiro quota work in #8726 lands. | | `bob` | `bob` | Provide `HIVE_BOB_API_KEY` or `/secrets/bob_api_key` for pods; contributor mode requires `BOB_API_KEY` (legacy `BOBSHELL_API_KEY` also accepted). | Hive uses API-key auth headlessly and accepts the Bob license at launch. | | `codex` | `codex` | Install `@openai/codex` and run `codex login --device-auth` for subscription/OAuth auth. The CLI stores credentials in `CODEX_HOME/auth.json` (default `${HOME}/.codex/auth.json`); API-key mode can use `CODEX_API_KEY`/`OPENAI_API_KEY` or a populated auth file, but it is not required for subscription users. | Hive gives each agent its own `CODEX_HOME` and probes `auth.json` for OAuth tokens/API-key state (or API-key env presence). Contributor mode keeps `--ask-for-approval on-request`, grants the exact `HIVE_WORKSPACE_DIR` tree with `--add-dir`, and defaults `approvals_reviewer` to `auto_review` so an unattended task never waits on the contributor. The `--sandbox` value is resolved at launch rather than fixed (#6653): `workspace-write` wherever bubblewrap can actually create the user namespace it needs — local mode, and containers started with a relaxed seccomp profile — and `danger-full-access` only inside the contributor container when that namespace is denied, where the container is already the boundary and asking for a nested one failed every command. Override with `HIVE_CODEX_APPROVAL_POLICY`/`HIVE_CODEX_SANDBOX_MODE`/`HIVE_CODEX_APPROVALS_REVIEWER`, or set `HIVE_CODEX_DANGEROUSLY_BYPASS_APPROVALS_AND_SANDBOX=1` only when you intentionally want the old bypass posture. `AGENT_REASONING_EFFORT` is passed to Codex as `-c model_reasoning_effort="..."` on the contributor-relay path; server-launched agents use the per-agent `reasoning_effort` config field (`minimal`\|`low`\|`medium`\|`high`\|`xhigh`) the same way since #6163. | diff --git a/docs/inference-backends.md b/docs/inference-backends.md index c26b8369d0..4d5ef6030a 100644 --- a/docs/inference-backends.md +++ b/docs/inference-backends.md @@ -4,6 +4,20 @@ Hive can route agents through OpenAI-compatible model gateways instead of a subs See [Gateway-path tier](../src/docs/backend-support-tiers.md#gateway-path-tier) for which dashboard/agent features (terminal access, model discovery, token metering, login) are guaranteed, best-effort, or not applicable on this path, and what a gateway smoke check must prove. +## Apple MLX: local contributor inference, not a hosted gateway + +ClankeR offers **Apple MLX** on `/contribute`, using the actual Pi coding +backend with an `mlx/` provider. MLX-LM runs natively on an Apple Silicon +Mac (macOS 14+, native Python 3.10+); Pi supplies tools in the contributor +container via Docker Desktop host networking. It is not a new `backend: mlx` +for hosted agents or a Governor Model Gateway. + +Use the dedicated `just contribute-mlx-serve`, explicit +`just contribute-mlx-setup --verify-tools`, and `just contribute-mlx` +workflow. Models are user-managed, must support structured tools, and consume +shared host RAM. See [installation and troubleshooting](../src/docs/contributor-relay.md#apple-mlx-local-inference) +for prerequisites, Pi registration, loopback restrictions and verification limits. + ## Looking for Copilot (or Claude, Codex, Gemini…)? It is not a Model Gateway Subscription CLI backends — `copilot`, `claude`, `codex`, `gemini`, `goose`, diff --git a/src/Dockerfile.contributor b/src/Dockerfile.contributor index 9ee01e3e59..43e021b52d 100644 --- a/src/Dockerfile.contributor +++ b/src/Dockerfile.contributor @@ -536,6 +536,8 @@ COPY bin/contributor-relay.js /usr/local/bin/ COPY bin/contributor-relay.sh /usr/local/bin/ COPY bin/lib/ /usr/local/bin/lib/ COPY bin/pi-backend.js /usr/local/bin/ +COPY bin/mlx-backend.js /usr/local/bin/ +COPY bin/mlx-pi-extension.js /usr/local/bin/ # #7925: the relay runs this against the task checkout's .hive/tools before # typing the prompt; it must sit beside contributor-relay.js. COPY bin/repo-toolchain.sh /usr/local/bin/ diff --git a/src/docs/contributor-relay.md b/src/docs/contributor-relay.md index b5486e9acd..302204b4c3 100644 --- a/src/docs/contributor-relay.md +++ b/src/docs/contributor-relay.md @@ -200,6 +200,170 @@ The first-task route ends above. The following sections cover custom launch sett Operators can publish a short **Help & community** list with `contribute.help_links` (Governor → Hub and `/contribute` Management). Onboarding and Operations show it, and `auth_ok` sends it for the relay to print once. Use joinable community links: Discord `https://discord.com/channels//` URLs require existing server membership; `https://hivecommons.dev/discord` lets newcomers join. +## Apple MLX local inference + +This optional **local contributor** route uses the existing **Pi coding agent** +with a custom `mlx` provider. MLX is the inference framework; **MLX-LM is not a +coding agent**. Pi owns file edits, shell/test tools, streamed tool execution +and conversation history; ClankeR retains assignment, GitHub credentials, +cancellation, progress and PR-result reporting. There is no hosted-provider +fallback, no new hub backend, and no change to other Pi providers. +The bundled `mlx-pi-extension.js` delegates to Pi's existing OpenAI-compatible +stream implementation with a loopback-only, redirect-rejecting fetch transport. +The private `hive-mlx` API name intentionally cannot run without this extension, +so a missing/failed extension cannot silently bypass the transport boundary. + +### Supported machines and boundaries + +- **Apple Silicon Macs only**, macOS **14+**, native arm64 Node and **Python + 3.10+**. Intel Macs, Rosetta processes and Linux inference hosts are not + supported by this integration. See the [MLX installation requirements](https://ml-explore.github.io/mlx/build/html/install.html). +- The protocol was checked against **MLX-LM v0.32.2**'s + [server implementation](https://github.com/ml-explore/mlx-lm/blob/v0.32.2/mlx_lm/server.py) + and Pi's [custom model configuration](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/models.md). + The contributor image pins Pi 1.4.0; this route requires **Pi 1.4.0+** for its + guarded inference transport. Other MLX-LM versions must pass the same + streaming tool-call/result check; older text-only servers will fail it. +- MLX-LM runs **natively on the Mac**, outside the Linux relay container. + The container does not install MLX or access the Apple GPU. Use **Docker + Desktop 4.34+** with **Settings → Resources → Network → Enable host + networking** enabled by you. See [Docker's host networking limitations](https://docs.docker.com/engine/network/drivers/host/#docker-desktop), + including incompatibility with Enhanced Container Isolation. This reuses Pi's + existing `--network host` exception and exposes host-local services to the + agent container; filesystem/config staging isolation remains unchanged. +- **Podman machine and Kubernetes are not supported** for this Mac loopback + route: their `localhost` is not the Mac. Do not solve that by making MLX-LM + listen on `0.0.0.0`. Only literal loopback HTTP URLs ending in `/v1` are + accepted; endpoint redirects, credentials in URLs and hosted URLs are refused. +- Host execution (`just contribute-hive pi local`) retains Pi's existing + refusal without `HIVE_PI_DANGEROUSLY_RUN_UNCONFINED=1`. Pi has **no host + sandbox** on that path; the container is the recommended coding boundary. + +### Explicit setup (source checkout) + +On your chosen hive's `/contribute` page, select **Apple MLX**, macOS and +Containerized mode, then enter your already-downloaded model's exact ID or +absolute path. The page generates these actual `just` commands; the public +hub's `/contribute#apple-mlx` section links here too. + +Install `just`, `gh`, native Node **22.19+**, and Pi using +[its official instructions](https://pi.dev), and prepare a **separate native +Python virtualenv** yourself. These are instructions, not automatic setup: +ClankeR never installs packages, downloads weights, automatically starts a +server, or adjusts system memory limits. + +```bash +npm install -g @earendil-works/pi-coding-agent@1.4.0 +python3 -m venv .venv-mlx +.venv-mlx/bin/python -m pip install 'mlx-lm==0.32.2' +export HIVE_MLX_PYTHON="$PWD/.venv-mlx/bin/python" +export HIVE_MLX_ENDPOINT=http://127.0.0.1:8080/v1 +``` + +Choose and download your model **yourself**, within your available RAM budget. +Use a model whose tokenizer/chat template and MLX-LM parser support structured +function calling and tool-result messages. **Not every MLX model can do coding +tasks**, and passing the small protocol probe is not a coding-quality benchmark. +Weights, KV cache, long prompts and generation all consume the Mac's **shared +RAM**. The relay container's 4-GiB limit does **not** cap MLX on the host. Leave +headroom for macOS and other workloads; do not increase wired-memory limits. +The [MLX-LM README](https://github.com/ml-explore/mlx-lm#long-prompts-and-generations) +discusses prompt/cache memory trade-offs. + +In a separate terminal, from the checkout, start the server explicitly with +an **already downloaded** model directory (or fully cached Hub ID). +`contribute-mlx-serve` validates the native runtime, forces Hugging Face +offline, and runs MLX-LM in the foreground on the configured loopback endpoint: + +```bash +HIVE_MLX_PYTHON="$PWD/.venv-mlx/bin/python" \ + just contribute-mlx-serve /Users/YOU/models/tool-coder +``` + +Stop it with Ctrl-C when finished; stopping the relay does not unload this +separately managed host server. A missing cached model fails rather than +downloading. The equivalent direct command is +`HF_HUB_OFFLINE=1 "$HIVE_MLX_PYTHON" -m mlx_lm.server --model /Users/YOU/models/tool-coder --host 127.0.0.1 --port 8080`. + +Use the **exact ID** returned by +`curl --fail http://127.0.0.1:8080/v1/models`: for a local directory this is its +resolved absolute path; a cached Hub model may instead be listed as +`mlx-community/`. Paths containing whitespace are not supported by Pi's +contributor model-token contract. Do not select MLX-LM's `default_model` alias: +ClankeR must declare the actual chosen model to the hive's Model Filter. + +The following command **explicitly opts in to two bounded inference requests** +(up to 256 output tokens and two minutes each). It checks a streamed function +call and a tool-result round trip; its dummy tool never edits files or runs a +shell command. Run it only when you have chosen to load the model: + +```bash +just contribute-mlx-setup /Users/YOU/models/tool-coder --verify-tools +export AGENT_MODEL=mlx//Users/YOU/models/tool-coder +# Use the URL of the public hive you chose, not the hub directory itself. +export HIVE_HUB=https://YOUR-CHOSEN-HIVE +just contribute-check pi +just contribute-setup pi +just contribute-mlx +``` + +`just contribute-mlx` is the MLX-specific launch entrypoint. It requires an +`mlx/...` selection and delegates to the existing `just contribute-hive pi` +coding workflow using Docker; it cannot silently launch another Pi provider. +An explicitly exported `AGENT_MODEL=mlx/...` wins over a saved model for this +MLX launch only; otherwise the saved selection must already be `mlx/...`. +Other Pi launch commands retain their existing profile precedence. +`just contribute-mlx local` preserves the existing native Pi unconfined +opt-in gate; it does not set that dangerous flag for you. + +For a Hub model ID, the corresponding selection is +`AGENT_MODEL=mlx/mlx-community/`. Setup preserves unrelated providers +but replaces Pi's `mlx` provider in `~/.pi/agent/models.json`, and writes a +matching `hive-mlx.json` receipt there. No provider credentials are needed: +Pi's `mlx-local` key is an inert availability marker, not a cloud key. +`PI_CODING_AGENT_DIR` is supported for native/direct invocation; the Justfile +container staging path uses the standard `~/.pi/agent` directory, so leave +that override unset for the commands above. + +To persist the selection, add your `AGENT_MODEL=mlx/...` line to the existing +private `~/.config/hive/contributor.env` **after** registration; do not replace +its hub/token profiles. Keep `HIVE_MLX_PYTHON` pointing to the server's +virtualenv on subsequent host launches. Optional setup variables +`HIVE_MLX_CONTEXT_WINDOW` (default `8192`) and `HIVE_MLX_MAX_TOKENS` (default +`2048`) set Pi's model metadata; choose limits your model/runtime actually +supports, with output tokens smaller than context. They are not host RAM caps. +The endpoint and budgets persist in Pi's provider configuration, not the hub. +Use a contributor image containing this integration; an older pinned image +does not acquire it just because the host checkout was updated. + +In the onboarding UI, choose **Apple MLX** and enter only the model ID/path; +the generated commands add the `mlx/` provider prefix. Advanced users can +still select **Pi** and supply the full `mlx/...` selection themselves. +Registration reports backend `pi`, provider `mlx` and that exact model through +the existing protocol. The hive may still reject it under its Model Filter or +trust policy; MLX setup never changes those policies. Both existing interactive +and headless Pi execution paths are retained. + +### Troubleshooting and verification limits + +Startup and task launches perform bounded **model-list checks only**, not +inference probes. Missing runtime, unsupported platforms, missing models, +changed provider configuration and unreachable endpoints fail explicitly; +reconfigure with `--verify-tools` after changing the endpoint, model, tokenizer +or runtime. A receipt records a successful probe, not proof that future weights +or responses are unchanged. If it works on the host but not in the container, +verify Docker Desktop host networking, not a bridge-container `localhost`. +If Pi reports tool/parser errors or context exhaustion, use a supported +tool-capable model, check its chat template and lower your chosen budgets. +Task errors and cancellation use the normal Pi failure/revocation paths; +ClankeR never substitutes a hosted model. + +CI exercises mocked streaming HTTP, model/config persistence, platform failures +and the Pi task lifecycle without a GPU or weights. Actual Apple Silicon model +inference and Docker Desktop connectivity were **not exercised** while +implementing this integration; validate your chosen model on your own Mac +before lending it to a hive. + ## Docker Compose workflow
diff --git a/src/docs/env-vars.md b/src/docs/env-vars.md index 9bc216ec03..842849e5e5 100644 --- a/src/docs/env-vars.md +++ b/src/docs/env-vars.md @@ -498,6 +498,10 @@ With two or more providers configured, `/login` renders a provider picker; with | `HIVE_COMMONS_NEEDIEST_REFRESH_MS` | No | `60000` | In `neediest`, milliseconds between `/api/contribute/status` refreshes per subscribed hub. `0` disables the interval. | | `AGENT_BACKEND` | No | `claude` | Contributor/agent CLI backend selector. | | `AGENT_MODEL` | No | backend default, or `GOOSE_MODEL` for Goose fallback | Contributor/agent model override. | +| `HIVE_MLX_PYTHON` | For optional MLX when `python3` is not its native environment | `python3` | Native Apple Silicon Python 3.10+ virtualenv executable containing MLX/MLX-LM; metadata-only preflight never initializes the GPU. [MLX setup](contributor-relay.md#apple-mlx-local-inference). | +| `HIVE_MLX_ENDPOINT` | No | `http://127.0.0.1:8080/v1` | Optional MLX setup/serve endpoint. Only literal loopback HTTP `/v1` URLs; no credentials, redirects or public hosts. Setup persists it in Pi's `mlx` provider. Docker Desktop host networking connects the relay container to the Mac. | +| `HIVE_MLX_CONTEXT_WINDOW` | No | `8192` | Pi model context metadata at explicit MLX setup; positive integer. Not a host-RAM limit. | +| `HIVE_MLX_MAX_TOKENS` | No | `2048` | Pi output metadata at explicit MLX setup; positive integer smaller than context. Not a host-RAM limit. | | `CONTRIBUTOR_MODE` | No | `interactive` | Contributor relay mode: `interactive` uses tmux; `headless` uses one-shot CLI execution for supported backends. | | `HIVE_SESSION` | No | backend name (`AGENT_BACKEND`) | Optional session label for running multiple relays concurrently under one GitHub account. The hub keys task leases, assignment cooldowns, failure streaks, and ownership fences on `ContributorID#session`, so distinctly labeled relays hold independent task slots; auth, trust tier, model admission, and rate-limit accounting stay per-account. Sanitized to `[A-Za-z0-9._-]`, max 32 bytes. Set to the empty string to opt out (bare per-account identity, the historical single-session behavior). See `src/docs/contributor-relay.md`, "Running multiple backends under one account". | | `HIVE_AGENT_ROLE` | No | empty string | Optional contributor role claim sent during relay authentication (for example `scanner`, `quality`, or `outreach`) so the hub can apply role-aware policy. Whitespace is trimmed. | diff --git a/src/docs/integrations.md b/src/docs/integrations.md index db761f2718..ba3a237bac 100644 --- a/src/docs/integrations.md +++ b/src/docs/integrations.md @@ -41,6 +41,18 @@ container mode by default; local mode needs an explicit opt-in. OmnigentOmnigentOpt-inT3backend-support-tiers.md +## Local contributor inference + +| Integration | Status | Execution and limitations | Docs | +| --- | --- | --- | --- | +| Apple MLX / MLX-LM through Pi | **Opt-in** | ClankeR on Apple Silicon macOS 14+, native Python 3.10+, Pi 1.4.0+; user-managed tool-capable models. MLX-LM runs on the Mac; Pi executes tools inside the contributor container with Docker Desktop host networking. No cloud fallback. Live Apple GPU inference remains unverified. | [Install and use with just](contributor-relay.md#apple-mlx-local-inference) | + +Apple MLX is a first-class inference-engine choice on `/contribute`, mapped to +the actual `pi` coding backend and `mlx/` provider selection. It is not +a standalone coding CLI, hosted gateway, identity provider, or Apple endorsement. +`KNOWN_BACKENDS` correctly continues to list coding executors, not inference +frameworks. + ## Work sources and trackers The governor reads work through one provider contract. The adapters live in diff --git a/src/pkg/dashboard/api_contribute_test.go b/src/pkg/dashboard/api_contribute_test.go index 94f011339c..5870a24695 100644 --- a/src/pkg/dashboard/api_contribute_test.go +++ b/src/pkg/dashboard/api_contribute_test.go @@ -469,7 +469,7 @@ func TestContributeLitellmFlavorsMapToLitellmSetup(t *testing.T) { for _, want := range []string{ // Flavor → real Justfile backend map, and its two consumers. - `var SETUP_BACKEND={openrouter:'litellm',vllm:'litellm','llm-d':'litellm',watsonx:'litellm'};`, + `var SETUP_BACKEND={openrouter:'litellm',vllm:'litellm','llm-d':'litellm',watsonx:'litellm',mlx:'pi'};`, `function setupBackend(v){return SETUP_BACKEND[v]||v;}`, `var backend=setupBackend(cli);`, `' 4. just contribute-setup '+setupBackend(v)+'\n'+`, diff --git a/src/pkg/dashboard/contribute_landing.go b/src/pkg/dashboard/contribute_landing.go index e810c5f254..65cbf735f4 100644 --- a/src/pkg/dashboard/contribute_landing.go +++ b/src/pkg/dashboard/contribute_landing.go @@ -311,6 +311,7 @@ body{font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;backgrou h1{font-size:var(--fs-3xl);margin-bottom:var(--sp-4)} .subtitle{color:var(--text-muted);font-size:1.1rem;margin-bottom:var(--sp-9)} .subtitle-discord{font-size:var(--fs-md);margin-top:var(--sp-0);margin-bottom:var(--sp-9)} +.mlx-note{display:none;margin-bottom:var(--sp-5);font-size:var(--fs-sm);color:var(--text-muted)} .discord-link{color:var(--cc-accent);font-weight:600} .stat-row{display:grid;grid-template-columns:repeat(auto-fit,minmax(80px,1fr));gap:10px;margin-bottom:var(--sp-8)} .stat{background:var(--surface-2);border:var(--line-width) solid var(--line-subtle);border-radius:var(--r-lg);padding:var(--sp-5) var(--sp-4);text-align:center;box-shadow:var(--shadow-card)} @@ -1610,13 +1611,14 @@ select.admin-act{min-width:0;max-width:100%%} - +