@platless/axom-cli 0.1.0 → 0.5.9

package/dist/workstation/acp/builds/install/uv.js

@@ -0,0 +1,254 @@
+/**
+ * uvx-distributed adapters as daemon-owned, per-version builds (spec 2026-10-11 §6.2, Task 15b):
+ * `uv tool install` with `UV_TOOL_DIR=<build>/tools` and `UV_TOOL_BIN_DIR=<build>/bin`, so every
+ * version lives in its own `uv/<pkg>/<version>/` and nothing is written to the user's `uv tool dir`
+ * or `~/.local/bin`. Interpreters uv has to download go to the daemon-owned `uv/.python/`.
+ *
+ * ## Installed in place, published by a marker (ruling)
+ *
+ * A uv tool environment embeds its absolute location (entry shebang, bin symlink, receipt — measured,
+ * see `uvxInstall.ts`), so it cannot be staged and renamed like npm and binary trees. Instead, under
+ * the agent lock **and** a per-tree lock:
+ *
+ * 1. a tree with a valid `.axom-uv-build.json` is complete and is reused as is (no `uv` at all);
+ * 2. otherwise anything at that path is the remains of a killed install — moved to `.trash/`;
+ * 3. `uv tool install` runs straight into the final directory; any failure moves it to `.trash/`;
+ * 4. the entry is resolved from that build's own `uv tool list --show-paths` (same env);
+ * 5. the marker is written **last** (temp + fsync + rename + directory fsync).
+ *
+ * A daemon killed anywhere before step 5 leaves a tree without a marker: never recorded, never
+ * launched, replaced by the next Install. Killed after step 5 but before the `builds.json` commit, the
+ * next Install adopts the tree without running `uv` (the same "complete but unrecorded" rule as npm).
+ *
+ * Launch never runs `uv`: `Build.launch` names the tool's own executable inside the build, which runs
+ * with the absolute venv interpreter its shebang names.
+ */
+import { existsSync, realpathSync, statSync } from 'node:fs';
+import { mkdir, readFile, rm } from 'node:fs/promises';
+import path from 'node:path';
+import { assertSafeVersion, buildIdFor, inside, normalizeUvPackageName, UV_PYTHON_BIN_DIR, UV_PYTHON_DIR, uvBuildDir } from '../model.js';
+import { writeFileDurably } from '../store.js';
+import { findUvTool, listUvTools, parseUvxSpec, UV_PROBE_TIMEOUT_MS, uvToolEntrypointFrom } from '../../uvxInstall.js';
+/** Written last into a uv build; its presence (and agreement with the path) is what "complete" means. */
+export const UV_BUILD_MARKER = '.axom-uv-build.json';
+/**
+ * The env every `uv` call for the build at `buildDir` runs with: its own tool and bin directories, and
+ * the daemon-owned interpreter directories. Laid over the daemon's environment, so a user's own uv
+ * configuration (an index mirror, `UV_CACHE_DIR`) still applies — only *where tools go* is ours.
+ */
+export function uvBuildEnv(root, buildDir) {
+    return {
+        UV_TOOL_DIR: path.join(buildDir, 'tools'),
+        UV_TOOL_BIN_DIR: path.join(buildDir, 'bin'),
+        UV_PYTHON_INSTALL_DIR: inside(root, UV_PYTHON_DIR),
+        UV_PYTHON_BIN_DIR: inside(root, UV_PYTHON_BIN_DIR),
+    };
+}
+export async function readMarker(buildDir, name, version) {
+    let text;
+    try {
+        text = await readFile(path.join(buildDir, UV_BUILD_MARKER), 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return { state: 'absent' };
+        return { state: 'unreadable', reason: errorText(error) };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        return { state: 'unreadable', reason: `marker is not JSON (${errorText(error)})` };
+    }
+    if (parsed.schema !== 1 || parsed.package !== name || parsed.version !== version || typeof parsed.entry !== 'string') {
+        return { state: 'mismatch', reason: `marker names ${String(parsed.package)} ${String(parsed.version)}` };
+    }
+    try {
+        if (!statSync(inside(buildDir, parsed.entry)).isFile())
+            return { state: 'mismatch', reason: `entry ${parsed.entry} is not a file` };
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return { state: 'mismatch', reason: `entry ${parsed.entry} is missing` };
+        return { state: 'unreadable', reason: errorText(error) };
+    }
+    return { state: 'valid', marker: parsed };
+}
+const errorText = (error) => (error instanceof Error ? error.message : String(error));
+/** Whether any agent's record in `builds.json` names `dir` — such a tree is never thrown away by an install. */
+async function referenced(store, dir) {
+    const document = await store.read();
+    return Object.values(document.agents).some((agent) => Object.values(agent.builds ?? {}).some((build) => build.dir === dir));
+}
+/**
+ * uv's own words for "no interpreter that fits, and none it could download" — only these trigger the
+ * fallback to an interpreter the user's own uv already knows; any other failure is that failure.
+ */
+const INTERPRETER_UNAVAILABLE = [
+    /No interpreter found/i,
+    /No (?:suitable |compatible )?Python (?:installation|interpreter|version)s? (?:found|available)/i,
+    /Failed to (?:download|install|fetch) (?:managed )?(?:cpython|python|pypy)/i,
+    /python-build-standalone/i,
+    /does not satisfy Python\s*[<>=!~]/i,
+];
+export function interpreterUnavailable(error) {
+    return !!error && INTERPRETER_UNAVAILABLE.some((pattern) => pattern.test(error));
+}
+/** The Python request uv's message names (`>=3.12` in "No interpreter found for Python >=3.12 in …"), if any. */
+export function requestedPython(error) {
+    const named = error?.match(/No interpreter found for (?:Python )?(\S+(?: \S+)?) in /i)?.[1]
+        ?? error?.match(/does not satisfy Python\s*([<>=!~]=?\s*[0-9][0-9.*]*)/i)?.[1];
+    return named?.replace(/\s+/g, '');
+}
+/**
+ * `uv tool install` into a build, with one fallback (ruling 15c): the first attempt runs with the build's
+ * env (`UV_PYTHON_INSTALL_DIR` under the store), which hides the user's uv-managed interpreters. When it
+ * fails because no suitable interpreter could be found or downloaded (an offline first install, say),
+ * `uv python find [<request>]` is run with the user's own, unmodified environment — read-only discovery,
+ * nothing is written to the user's uv directories — and, if it names one, the install is retried with
+ * `--python <that path>`. `reset` clears the failed attempt's leftovers before the retry.
+ */
+async function uvToolInstall(options) {
+    const { runUv, requirement, env, timeoutMs } = options;
+    const install = (python) => runUv(['tool', 'install', ...options.extraArgs, ...python, requirement], timeoutMs, env);
+    const first = await install([]);
+    if (first.ok || !interpreterUnavailable(first.error))
+        return first;
+    const request = requestedPython(first.error);
+    // No env argument: the user's default uv environment, read-only.
+    const found = await runUv(['python', 'find', ...(request ? [request] : [])], UV_PROBE_TIMEOUT_MS);
+    const python = found.ok ? found.stdout.trim().split('\n').pop()?.trim() : undefined;
+    if (!python || !path.isAbsolute(python))
+        return first;
+    console.info(`[acp-builds] uv found no interpreter for ${requirement} of its own; retrying with the user's ${python}`);
+    await options.reset();
+    return { ...await install(['--python', python]), python };
+}
+/** `absolute` (an executable uv reported) as a posix path relative to `buildDir`, following symlinks; refuses anything outside. */
+function entryWithin(buildDir, absolute) {
+    const base = realpathSync(buildDir);
+    const target = realpathSync(absolute);
+    const relative = path.relative(base, target);
+    if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) {
+        throw new Error(`uv reported an executable outside its build directory: ${absolute}`);
+    }
+    return relative.split(path.sep).join('/');
+}
+/**
+ * The uv build for registry specifier `spec` (`pkg==1.2.3`, `pkg@1.2.3`, or unpinned `pkg`), installed
+ * if it is not complete on disk yet. Not committed — the caller does that under the agent lock it holds.
+ */
+export async function installUvBuild(options) {
+    const { store, runUv } = options;
+    const spec = parseUvxSpec(options.spec);
+    const name = normalizeUvPackageName(spec.name);
+    let version = spec.version;
+    if (version === undefined) {
+        const resolved = await resolveUnpinnedVersion(store, spec.name + spec.extras, name, runUv, options.timeoutMs);
+        if (!resolved.ok)
+            return resolved;
+        version = resolved.version;
+    }
+    assertSafeVersion(version);
+    const dir = uvBuildDir(name, version);
+    const buildDir = inside(store.root, dir);
+    return store.withTreeLock(dir, async () => {
+        const found = await readMarker(buildDir, name, version);
+        if (found.state === 'unreadable') {
+            return { ok: false, error: `The uv build at ${dir} cannot be checked (${found.reason}); it was left untouched.` };
+        }
+        let marker = found.state === 'valid' ? found.marker : undefined;
+        const downloaded = marker === undefined;
+        if (!marker) {
+            if (existsSync(buildDir)) {
+                // Without a valid marker this is a killed install's remains — unless a record names it, in which
+                // case it was a working build and something else is wrong: never delete it on a guess.
+                if (await referenced(store, dir)) {
+                    return {
+                        ok: false,
+                        error: `The uv build at ${dir} is recorded as installed but its marker is ${found.state === 'mismatch' ? `wrong (${found.reason})` : 'missing'}; it was left untouched.`,
+                    };
+                }
+                await store.discard(buildDir);
+            }
+            try {
+                await mkdir(buildDir, { recursive: true });
+                const env = uvBuildEnv(store.root, buildDir);
+                const requirement = `${spec.name}${spec.extras}==${version}`;
+                // `--compile-bytecode`: the interpreter then never writes `__pycache__` into the build while it
+                // runs, so a build stays byte-identical for as long as it exists.
+                const ran = await uvToolInstall({
+                    runUv, requirement, extraArgs: ['--compile-bytecode'], env, timeoutMs: options.timeoutMs,
+                    reset: async () => { await store.discard(buildDir); await mkdir(buildDir, { recursive: true }); },
+                });
+                if (!ran.ok) {
+                    await store.discard(buildDir);
+                    return { ok: false, error: ran.error ?? `uv tool install ${requirement} failed`, ...(ran.code === 'ENOENT' ? { uvMissing: true } : {}) };
+                }
+                const tools = await listUvTools(runUv, UV_PROBE_TIMEOUT_MS, env);
+                const installed = findUvTool(tools, name);
+                if (installed?.version !== version) {
+                    throw new Error(`uv installed ${name} ${installed ? `v${installed.version}` : 'nothing'} when ${requirement} was asked for`);
+                }
+                const picked = uvToolEntrypointFrom(name, tools);
+                if (!picked.ok) {
+                    throw new Error(picked.reason === 'ambiguous'
+                        ? `${name} ${version} declares several executables and none is named like the package: ${picked.candidates.join(', ')}`
+                        : `${name} ${version} installed no executable`);
+                }
+                marker = {
+                    schema: 1, package: name, version, entry: entryWithin(buildDir, picked.path),
+                    ...(ran.python ? { python: ran.python } : {}),
+                };
+                await writeFileDurably(path.join(buildDir, UV_BUILD_MARKER), `${JSON.stringify(marker, null, 2)}\n`);
+            }
+            catch (error) {
+                await store.discard(buildDir).catch(() => undefined);
+                return { ok: false, error: error instanceof Error ? error.message : String(error) };
+            }
+        }
+        const build = {
+            buildId: buildIdFor(version),
+            agentId: options.agentId,
+            kind: 'uv',
+            version,
+            package: name,
+            dir,
+            launch: { runtime: 'native', entry: marker.entry, args: [...options.args], env: { ...options.env } },
+            ...(typeof marker.python === 'string' ? { pythonFrom: marker.python } : {}),
+            registryVersion: options.registryVersion,
+            source: options.source,
+            installedBy: options.installedBy,
+            installedAt: (options.now ?? new Date()).toISOString(),
+        };
+        return { ok: true, build, downloaded };
+    });
+}
+/**
+ * An unpinned specifier names no build directory until uv has resolved it, and a uv tree cannot be
+ * moved afterwards. So the version is resolved by a throwaway install into staging (its tree is
+ * discarded), and the build is then installed pinned to exactly that version (from uv's cache).
+ */
+async function resolveUnpinnedVersion(store, requirement, name, runUv, timeoutMs) {
+    const staged = await store.stagingDir();
+    try {
+        const env = uvBuildEnv(store.root, staged);
+        const ran = await uvToolInstall({
+            runUv, requirement, extraArgs: [], env, timeoutMs,
+            reset: async () => {
+                for (const sub of ['tools', 'bin'])
+                    await rm(path.join(staged, sub), { recursive: true, force: true });
+            },
+        });
+        if (!ran.ok)
+            return { ok: false, error: ran.error ?? `uv tool install ${requirement} failed`, ...(ran.code === 'ENOENT' ? { uvMissing: true } : {}) };
+        const version = findUvTool(await listUvTools(runUv, UV_PROBE_TIMEOUT_MS, env), name)?.version;
+        if (!version)
+            return { ok: false, error: `uv reported success but ${requirement} is not in the installed tools` };
+        return { ok: true, version };
+    }
+    finally {
+        await store.discard(staged);
+    }
+}

package/dist/workstation/acp/builds/migrate.js

@@ -0,0 +1,195 @@
+/**
+ * Moving what an older CLI left on this machine into the build store (spec 2026-10-11 §6.2 "迁移").
+ *
+ * Before builds, npx agents ran out of npm's own `~/.npm/_npx/<hash>/node_modules` and binary agents
+ * out of `acp-adapters/<agentId>/<version>/`. Neither has a `builds.json` record, so without this every
+ * agent a user already had would read as not installed. Per agent, under its lock, once:
+ *
+ * - **npm**: the version the old launch path would have used (the *effective* version: registry, then
+ *   catalog, then runtime.json override — `requestedVersionOf` in `acpAgents.ts`) is looked up in
+ *   `_npx`. Found complete → copied into `npm/<sha16(name)>/<version>/pristine` (staging → rename) and,
+ *   patched or not, made current. Not found → the first open runs one Install (`AcpAgents.open`).
+ *   `_npx` itself is never modified or deleted: it is npm's, not ours.
+ * - **binary**: every `acp-adapters/<agentId>/<version>/` is renamed in place to `bin/<agentId>/<version>/`
+ *   (same filesystem, so the same inodes: a running binary keeps running), a symlink is left at the old
+ *   path for whatever a running adapter still reaches by path, and it is recorded; the version the old
+ *   launch path picked (the pinned one if present, else the highest) becomes current. The links are
+ *   never followed by the store itself (a symlink is not a legacy version) and are left for GC.
+ * - **uv**: nothing to move — the user's uv tool dir is not Axom's. The first open installs a build.
+ */
+import { cp, lstat, mkdir, readdir, readFile, readlink, realpath, rename, rm, stat, symlink } from 'node:fs/promises';
+import { constants, existsSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import path from 'node:path';
+import { inside, npmPristineDir, assertSafePackageName, assertSafeVersion } from './model.js';
+import { publishStaged } from './store.js';
+/** Directory names under the `acp-adapters` root that are the build store's own, never a legacy agent. */
+export const RESERVED_ROOT_NAMES = new Set(['npm', 'uv', 'bin', 'patched-npm', 'builds.json']);
+async function manifestOf(packageDir) {
+    try {
+        return JSON.parse(await readFile(path.join(packageDir, 'package.json'), 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The `node_modules` of an `_npx/<hash>` entry holding exactly `name@version`, complete: the package's
+ * own `package.json` names it at that version, and npm finished reifying the tree (npm 7+ writes the
+ * hidden lockfile `node_modules/.package-lock.json` last). A half-written entry is not a copy we take —
+ * the first open installs instead, which only costs a download. Entries are tried in name order, so
+ * the answer does not depend on directory enumeration order.
+ */
+export async function findNpxCopy(npmCache, name, version) {
+    assertSafePackageName(name);
+    const npxDir = path.join(npmCache, '_npx');
+    let entries;
+    try {
+        entries = (await readdir(npxDir)).sort();
+    }
+    catch {
+        return undefined;
+    }
+    for (const entry of entries) {
+        const nodeModules = path.join(npxDir, entry, 'node_modules');
+        const manifest = await manifestOf(path.join(nodeModules, ...name.split('/')));
+        if (manifest?.name !== name || manifest.version !== version)
+            continue;
+        if (!existsSync(path.join(nodeModules, '.package-lock.json')))
+            continue;
+        return nodeModules;
+    }
+    return undefined;
+}
+const within = (root, target) => target === root || target.startsWith(root + path.sep);
+/**
+ * Copy the `node_modules` tree at `source` to `destination` so that it no longer depends on `source`:
+ * relative symlinks that stay inside the tree (npm's `.bin/*` → `../pkg/…`) are kept verbatim (they
+ * resolve the same way in the copy); a symlink that leaves the tree, or an absolute one, is replaced by
+ * a copy of what it points at (dereferenced). Files are cloned where the filesystem can (reflink).
+ */
+export async function copyTreeSelfContained(source, destination) {
+    const root = await realpath(source);
+    await cp(root, destination, { recursive: true, verbatimSymlinks: true, mode: constants.COPYFILE_FICLONE, errorOnExist: true, force: false });
+    const links = (await readdir(root, { recursive: true, withFileTypes: true })).filter((entry) => entry.isSymbolicLink());
+    for (const link of links) {
+        const sourceLink = path.join(link.parentPath, link.name);
+        const relative = path.relative(root, sourceLink);
+        const copied = path.join(destination, relative);
+        const target = await readlink(sourceLink);
+        const resolved = path.resolve(path.dirname(sourceLink), target);
+        if (!path.isAbsolute(target) && within(root, resolved))
+            continue;
+        await rm(copied, { force: true });
+        if (within(root, resolved)) {
+            // Absolute but inside the tree: the same link, relative, so it points into the copy.
+            await symlink(path.relative(path.dirname(sourceLink), resolved), copied);
+            continue;
+        }
+        let real;
+        try {
+            real = await realpath(resolved);
+        }
+        catch {
+            // Dangling outside the tree: npm would not have run it either. Keep the link as it was.
+            await symlink(target, copied);
+            continue;
+        }
+        await cp(real, copied, { recursive: true, dereference: true, mode: constants.COPYFILE_FICLONE });
+    }
+}
+/**
+ * `npm/<sha16(name)>/<version>/pristine` made from an `_npx` copy (staging → rename). Already there →
+ * nothing copied. The caller holds the agent lock.
+ */
+export async function adoptNpxCopy(options) {
+    const { store, name, version } = options;
+    assertSafeVersion(version);
+    const final = inside(store.root, npmPristineDir(name, version));
+    const installed = await manifestOf(inside(path.join(final, 'node_modules'), name));
+    if (installed?.name === name && installed.version === version)
+        return { copied: false };
+    const staged = await store.stagingDir();
+    try {
+        await copyTreeSelfContained(options.nodeModules, path.join(staged, 'node_modules'));
+        const copied = await manifestOf(inside(path.join(staged, 'node_modules'), name));
+        if (copied?.name !== name || copied.version !== version)
+            throw new Error(`npx copy of ${name}@${version} changed while it was copied`);
+        const { published } = await publishStaged(staged, final);
+        return { copied: published };
+    }
+    finally {
+        await store.discard(staged);
+    }
+}
+/** The legacy (pre-build) binary version directories of `agentId`: `acp-adapters/<agentId>/<version>/`. */
+export async function legacyBinaryVersions(root, agentId) {
+    if (RESERVED_ROOT_NAMES.has(agentId) || agentId.startsWith('.'))
+        return [];
+    let entries;
+    try {
+        entries = await readdir(path.join(root, agentId), { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    return entries.filter((entry) => entry.isDirectory() && !entry.name.startsWith('.')).map((entry) => entry.name);
+}
+/**
+ * Rename `acp-adapters/<agentId>/<version>` to `bin/<agentId>/<version>`. `rename(2)` keeps every inode,
+ * so a process running from the old path keeps its executable and every file it already opened; and
+ * the old path is left as a symlink to the new one, so a running adapter that later opens or spawns a
+ * sibling **by path** (Antigravity ships its server and a helper side by side) still finds it.
+ * Refuses (returns false) across filesystems and when the destination already exists; never copies.
+ */
+export async function moveLegacyBinary(root, agentId, version, destination) {
+    const from = path.join(root, agentId, version);
+    if (!(await lstat(from)).isDirectory())
+        return false;
+    if (existsSync(destination))
+        return false;
+    await mkdir(path.dirname(destination), { recursive: true });
+    if ((await stat(from)).dev !== (await stat(path.dirname(destination))).dev) {
+        console.warn(`[acp-builds] ${from} is on another filesystem than ${destination}; left where it is.`);
+        return false;
+    }
+    // The link is made first, under a hidden temporary name beside the old path (dangling until the move),
+    // so the old path is missing only between the two renames below — never across a symlink creation
+    // that could fail or be slow. It cannot be closed entirely: the old path *is* the directory, and
+    // replacing a directory with a link in one step needs an exchange rename (`renameat2(RENAME_EXCHANGE)`
+    // / `renamex_np(RENAME_SWAP)`) that Node does not expose.
+    const link = path.join(path.dirname(from), `.${version}.link-${randomUUID()}`);
+    let linked = true;
+    try {
+        // A junction on Windows (no privilege needed; it wants an absolute target).
+        if (process.platform === 'win32')
+            await symlink(destination, link, 'junction');
+        else
+            await symlink(path.relative(path.dirname(from), destination), link, 'dir');
+    }
+    catch (error) {
+        linked = false;
+        console.warn(`[acp-builds] could not prepare a link at ${from} for adapters still running from it: ${String(error)}`);
+    }
+    try {
+        await rename(from, destination);
+    }
+    catch (error) {
+        if (linked)
+            await rm(link, { force: true }).catch(() => undefined);
+        const code = error.code;
+        if (code === 'EXDEV' || code === 'EEXIST' || code === 'ENOTEMPTY')
+            return false;
+        throw error;
+    }
+    if (linked) {
+        try {
+            await rename(link, from);
+        }
+        catch (error) {
+            await rm(link, { force: true }).catch(() => undefined);
+            console.warn(`[acp-builds] could not leave a link at ${from} for adapters still running from it: ${String(error)}`);
+        }
+    }
+    return true;
+}

package/dist/workstation/acp/builds/model.js

@@ -0,0 +1,128 @@
+/**
+ * The adapter **build** model (spec 2026-10-11 workstation-keepers §6.1/§6.2).
+ *
+ * A build is one immutable, daemon-owned install of one adapter version — the unit "which version
+ * does a new session use" and "which version is this running process" are answered in. Each agent
+ * has at most one `current` build in `<configDir>/acp-adapters/builds.json`; only Install/Update (and
+ * a CLI-certified pin or patch-set change, marked `currentSetBy: 'axom'`) move it. A registry refresh
+ * never does: it only makes the settings card offer Update.
+ *
+ * ## Layout (all under `<configDir>/acp-adapters/`, all staged then renamed into place)
+ *
+ * ```
+ * builds.json
+ * npm/<sha16(name)>/<version>/pristine/node_modules/…          # npm install --prefix
+ * npm/<sha16(name)>/<version>/patched/<digest>/node_modules/…  # copied from pristine (reflink first) + patched
+ * uv/<pkg>/<version>/{tools,bin}/ + .axom-uv-build.json          # UV_TOOL_DIR + UV_TOOL_BIN_DIR (see below)
+ * uv/.python/   uv/.python-bin/                                # UV_PYTHON_INSTALL_DIR / UV_PYTHON_BIN_DIR
+ * bin/<agentId>/<version>/…                                     # binary archives
+ * .staging/<uuid>/   .trash/<uuid>/
+ * ```
+ *
+ * A directory under `npm/` or `bin/` only ever appears by `rename(2)` of a complete staging tree,
+ * so its existence means "complete". It is still not *installed* until a record for it is committed
+ * to `builds.json`: an install killed between the rename and the commit leaves an unreferenced, complete
+ * tree that the next Install reuses instead of downloading again.
+ *
+ * **uv is the one exception to "appears only by rename"** (ruling, Task 15b): a uv tool environment
+ * embeds its own absolute path (the entry script's shebang names `<UV_TOOL_DIR>/<pkg>/bin/python`, the
+ * `UV_TOOL_BIN_DIR` entry is an absolute symlink, `uv-receipt.toml` records both), so a tree renamed
+ * after `uv tool install` no longer runs. uv installs straight into `uv/<pkg>/<version>/`, under a
+ * per-tree lock, and the tree only counts as complete once `.axom-uv-build.json` — written last, by
+ * temp + fsync + rename — names its entry. A tree without that marker (a killed install) is moved to
+ * `.trash/` by the next Install of that version and installed again; it is never recorded, never launched.
+ */
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+export const BUILDS_FILE = 'builds.json';
+export const STAGING_DIR = '.staging';
+export const TRASH_DIR = '.trash';
+export class AdapterNotInstalledError extends Error {
+    agentId;
+    constructor(agentId, detail) {
+        super(`Agent '${agentId}' has no installed adapter on this machine${detail ? ` (${detail})` : ''}. ` +
+            'Install it from the workstation\'s external agents settings.');
+        this.name = 'AdapterNotInstalledError';
+        this.agentId = agentId;
+    }
+}
+/**
+ * An open had to install the agent's adapter and the install is still running when the open's budget
+ * (`OPEN_INSTALL_BUDGET_MS`) ran out. The install goes on under the agent lock; retrying the open waits
+ * for it. The message is what the reader sees as the open's error.
+ */
+export class AdapterStillInstallingError extends Error {
+    agentId;
+    version;
+    constructor(agentId, agentName, version) {
+        super(`${agentName} adapter ${version} is still installing; try again shortly.`);
+        this.name = 'AdapterStillInstallingError';
+        this.agentId = agentId;
+        this.version = version;
+    }
+}
+const sha256 = (value) => createHash('sha256').update(value).digest('hex');
+/** A version string safe to use as one path segment. Registry/npm data must never escape the layout. */
+export function assertSafeVersion(version) {
+    if (!/^[0-9A-Za-z][0-9A-Za-z.+_-]{0,127}$/.test(version) || version.includes('..')) {
+        throw new Error(`Refusing unsafe adapter version '${version}'`);
+    }
+    return version;
+}
+/** An agent id safe to use as one path segment. */
+export function assertSafeAgentId(agentId) {
+    if (!/^[0-9A-Za-z][0-9A-Za-z._-]{0,127}$/.test(agentId) || agentId.includes('..')) {
+        throw new Error(`Refusing unsafe agent id '${agentId}'`);
+    }
+    return agentId;
+}
+export function assertSafePackageName(name) {
+    if (!/^(?:@[a-z0-9._-]+\/)?[a-z0-9._-]+$/i.test(name))
+        throw new Error(`Refusing unsafe npm package name '${name}'`);
+    return name;
+}
+export function buildIdFor(version, patchDigest) {
+    return patchDigest ? `${version}+axom.${patchDigest.slice(0, 8)}` : version;
+}
+export function labelFor(build) {
+    return { agentId: build.agentId, buildId: build.buildId, version: build.version, kind: build.kind };
+}
+const posix = (...parts) => parts.join('/');
+/** `npm/<sha16(name)>/<version>` — the version directory both npm kinds live under. */
+export function npmVersionDir(name, version) {
+    return posix('npm', sha256(assertSafePackageName(name)).slice(0, 16), assertSafeVersion(version));
+}
+export function npmPristineDir(name, version) {
+    return posix(npmVersionDir(name, version), 'pristine');
+}
+export function npmPatchedDir(name, version, digest) {
+    if (!/^[0-9a-f]{64}$/.test(digest))
+        throw new Error('Invalid patch digest');
+    return posix(npmVersionDir(name, version), 'patched', digest);
+}
+export function binaryBuildDir(agentId, version) {
+    return posix('bin', assertSafeAgentId(agentId), assertSafeVersion(version));
+}
+/** A Python package name normalised the PEP 503 way (`Fast_Agent.ACP` → `fast-agent-acp`), safe as one path segment. */
+export function normalizeUvPackageName(name) {
+    const normalized = name.toLowerCase().replace(/[-_.]+/g, '-');
+    if (!/^[a-z0-9](?:[a-z0-9-]{0,126}[a-z0-9])?$/.test(normalized))
+        throw new Error(`Refusing unsafe Python package name '${name}'`);
+    return normalized;
+}
+/** `uv/<pkg>/<version>` — one uv build; holds `tools/` (`UV_TOOL_DIR`) and `bin/` (`UV_TOOL_BIN_DIR`). */
+export function uvBuildDir(name, version) {
+    return posix('uv', normalizeUvPackageName(name), assertSafeVersion(version));
+}
+/** Interpreters uv downloads for builds (`UV_PYTHON_INSTALL_DIR`): daemon-owned, never the user's `~/.local/share/uv/python`. */
+export const UV_PYTHON_DIR = 'uv/.python';
+/** Where uv may link interpreter executables (`UV_PYTHON_BIN_DIR`) — never the user's `~/.local/bin`. */
+export const UV_PYTHON_BIN_DIR = 'uv/.python-bin';
+/** `relative` resolved under `root`, refusing anything that escapes it. */
+export function inside(root, relative) {
+    const base = path.resolve(root);
+    const target = path.resolve(base, ...relative.split('/'));
+    if (target !== base && !target.startsWith(base + path.sep))
+        throw new Error('Adapter build path escapes its directory');
+    return target;
+}