Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/workflows/v2-ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
72 changes: 72 additions & 0 deletions Justfile
Original file line number Diff line number Diff line change
Expand Up @@ -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/<model-id-or-absolute-path>"
echo " Setup: just contribute-mlx-setup <model-id-or-absolute-path> --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.
Expand Down Expand Up @@ -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"
Expand Down Expand Up @@ -925,6 +975,7 @@ contribute-hive backend="" mode="docker": check-version
echo "Not set up yet. Run: just contribute-setup <cli>"
exit 1
fi
_MLX_LAUNCH_MODEL="${HIVE_MLX_LAUNCH_MODEL:-}"
set -a
source "{{config_dir}}/gh-auth.env"
source "{{config_dir}}/contributor.env"
Expand Down Expand Up @@ -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/<model> 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
Expand All @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down
2 changes: 2 additions & 0 deletions bin/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <model> --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
Expand Down
6 changes: 6 additions & 0 deletions bin/contributor-agent.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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:-}"
}

Expand Down Expand Up @@ -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}\"'"
Expand Down
19 changes: 18 additions & 1 deletion bin/contributor-relay.js
Original file line number Diff line number Diff line change
Expand Up @@ -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/
Expand Down Expand Up @@ -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}` : '';
}

Expand Down Expand Up @@ -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] : [];
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down
52 changes: 51 additions & 1 deletion bin/contributor-relay.test.js
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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.
Expand Down
Loading
Loading