@socketsecurity/lib 6.0.8 → 6.0.9

package/CHANGELOG.md

@@ -5,6 +5,28 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [6.0.9](https://github.com/SocketDev/socket-lib/releases/tag/v6.0.9) - 2026-06-18
+
+### Added
+
+- **`external-tools/uv` — uv resolver.** Resolves Astral's `uv` Python package manager across three tiers (embedded VFS, then system PATH, then a downloaded GitHub release), matching the shape of the other `external-tools/*` tool resolvers. Exports `resolveUv`, `ResolvedUv`, `UvSource`, plus the per-platform asset map and download helpers.
+- **`external-tools/python/uv-install` — reproducible uv-project install helpers.** `uvSyncProject` installs a uv project at its exact pinned versions and refuses to proceed when those have drifted, so every machine gets the same result. `uvExportMaterialize` installs the same pinned versions into a content-addressed directory with no virtualenv, so the result is relocatable and embeddable in a single-file build. Concurrent callers serialize so two installs can't collide. The Python analog of the npm dlx install model.
+- **`external-tools/skillspector` — pinned-project resolution tier.** `skillspectorFromUv` installs SkillSpector from a fully pinned uv project (every version fixed) and returns its entry point, resolved ahead of the existing git-SHA fallback when a project directory and `uv` binary are supplied. Adds a `'uv'` source to the resolution result.
+- **`config/layers` — generic layered-config reader.** `readConfigLayers(name, { dirs })` reads a named config file from an ordered list of layer directories (lowest precedence first) and returns the layers that exist; absent or unparseable layers are skipped. `mergeConfigArray` concatenates one array-valued key across all layers, for lists that higher layers extend rather than replace. It carries no project-convention knowledge: the caller supplies the directories and the merge policy.
+- **`paths` — `_wheelhouse` tool-layout dirs and the agent-clone dir.** `getSocketRackDir` and `getSocketRackToolDir` locate the racked tool store, `getSocketWheelhouseBinDir` the PATH-handle directory that points into it, and `getSocketRepoClonesDir` the directory where agents clone external repos for reference (kept out of the projects tree so sibling-walking tooling never treats a clone as a fleet member).
+- **`ai` — offline/gated-model detection and fall-over.** `spawnTierWithFallback` walks a tier's cross-engine equivalence chain and runs the first engine that is both installed and authenticated, so a request still completes when the preferred model is down, gated, or unkeyed. `isModelUnavailable` recognizes a down-or-gated model from the engine's actual output rather than a brittle literal-string match. The `ai/route` resolver and `ai/subagent-status` reader are exposed as their own entry points.
+- **`fs/copy` — recursive copy with three destination modes.** `copy(from, to, { mode })` copies a file or directory tree. `CopyMode` chooses how an existing destination is treated: `'overlay'` (the default: overwrite collisions, keep destination-only files), `'pave'` (the destination becomes an exact mirror of the source via an atomic sibling-temp-then-rename swap, so no stale files survive and a partial tree is never observed), or `'fill'` (no-clobber: add only what is missing, never overwrite). Also accepts `filter`, `dereference`, and an abort `signal`.
+- **`node/requireFrom` — relative `require` bound to the caller's directory.** `requireFrom(fromUrl, specifier)` resolves a relative specifier (`./x`, `../y`) from the caller's own directory, passed as `import.meta.url`, so relative loads bind to the right base when modules run unbundled (for example AOT-compiled from source, where each module sits at its own nested path). Builtins and bare packages resolve as before.
+- **`secrets` — proteus broker credential tier.** The credential resolver gains a broker layer in the documented order (explicit, then env, then broker, then keychain): it connects to the broker's runtime socket, requests the value, and self-gates. No socket means no broker, so it returns `undefined` and falls through to the keychain. Async only (absent from `resolveSync`) and skipped under `allowEnvOnly`. Existing `resolveProviderCredential` call sites are unchanged.
+- **`paths` — `getRuntimeSocketPath` and `getXdgRuntimeDir` for daemon sockets.** One resolver a daemon and its clients both call to locate a runtime socket: the XDG runtime dir when present, a `$TMPDIR/<name>-<uid>` fallback, or a named pipe on Windows.
+- **`llms.txt` — discovery index for AI agents.** `pnpm run docs` now also emits a publish-safe `llms.txt` at the package root that links each export subpath to its shipped `.d.mts` declaration, giving an agent one file to read after installing. It ships in the published tarball.
+- **`packages/manifest` — `trimPublishManifest`.** Returns a shallow copy of a `package.json` that omits dev/build-only top-level fields (`devDependencies`, `scripts` by default) so a published tarball and its npm metadata stay lean. `drop` overrides the field set; `keep` retains a field even when dropped (e.g. a runtime `postinstall`). The original object is left intact.
+
+### Changed
+
+- **`integrity` — one `Hash` currency (breaking).** Hashes are modeled as a single concept, a `Hash` carrying algorithm, hex, and sri, rather than an integrity-vs-checksum type duality, so the algorithm is explicit on every value. Adds `parseHash` (encoding- and length-aware), `computeHash` (sha512 default), `verifyHash(bytes, expected)` (verifies against the expected hash's declared algorithm), `equalHashes` (encoding-agnostic, and never equal across algorithms), `makeHash`, and `HashMismatchError`. Breaking: `verifyHash` now takes `(bytes, expected)`, not `(expected, computed)`, and `DlxHashMismatchError` is a deprecated alias of `HashMismatchError`. Back-compat shims remain: `checksumToIntegrity`, `integrityToChecksum`, `normalizeHash`, `computeHashes`, `isChecksum`, `isIntegrity`, `parseIntegrity`.
+- **`fleet/repo-config` is now a thin wrapper over `config/layers`.** `resolveRepoConfig` (the fleet default layered under a per-repo override) and `mergeRepoConfigArray` stay at `fleet/repo-config`; the generic, convention-free primitives moved to the new `config/layers` entry. `resolveRepoConfig` callers see no behavior change.
+
 ## [6.0.8](https://github.com/SocketDev/socket-lib/releases/tag/v6.0.8) - 2026-06-11
 
 ### Added

package/dist/ai/route.d.mts

@@ -32,15 +32,16 @@ export interface TierCandidate {
 }
 /**
  * Why the resolver returned what it did. - `preferred` — the tier's
- * first-choice engine was available + keyed. - `fellback` — the preferred
- * engine was missing/unkeyed; an equivalent on another engine was used (`from`
- * names the original tier).
+ * first-choice engine was available + keyed. - `fell-over` — the preferred
+ * engine was missing/unkeyed; an equivalent on another engine was used
+ * (`requestedTier` names the tier originally asked for). Matches the
+ * `fellOver` vocabulary `spawnTierWithFallback` (spawn.mts) reports.
  */
-export type TierResolveReason = 'fellback' | 'preferred';
+export type TierResolveReason = 'fell-over' | 'preferred';
 export interface TierResolution {
     readonly candidate: TierCandidate;
     readonly reason: TierResolveReason;
-    readonly from?: AiTier | undefined;
+    readonly requestedTier?: AiTier | undefined;
 }
 /**
  * The context a caller probes once and passes in: which engine CLIs exist, and
@@ -62,8 +63,20 @@ export declare function isCandidateUsable(candidate: TierCandidate, ctx: RouteCo
  * Resolve a tier to the best available concrete target. Prefers the tier's
  * first-choice (Claude) candidate; if its engine is missing or unkeyed, walks
  * the cross-engine equivalence ladder and returns the first usable equivalent,
- * tagging the result `fellback` with the original tier in `from`. Returns
- * `undefined` only when NOTHING in the chain is usable — the caller then skips
- * the work or surfaces a "no AI engine available" message.
+ * tagging the result `fell-over` with the original tier in `requestedTier`.
+ * Returns `undefined` only when NOTHING in the chain is usable — the caller
+ * then skips the work or surfaces a "no AI engine available" message.
  */
 export declare function resolveTier(tier: AiTier, ctx: RouteContext): TierResolution | undefined;
+/**
+ * The ORDERED list of usable candidates for a tier — the runtime-fallback
+ * sequence. `resolveTier` returns only the single best pick (good when you
+ * trust it will work); this returns every usable candidate in preference order
+ * so a caller can advance to the next when one fails AT RUNTIME — e.g. the
+ * preferred model is installed + keyed (so it passes `isCandidateUsable`) yet
+ * its CLI reports it offline at spawn ("Claude Fable 5 is currently
+ * unavailable"). The static check can't predict an outage; only the spawn
+ * result can, so the caller walks this list until a spawn returns without the
+ * `unavailable` flag. Empty when nothing in the chain is usable.
+ */
+export declare function usableTierCandidates(tier: AiTier, ctx: RouteContext): TierCandidate[];

package/dist/ai/route.js

@@ -131,9 +131,9 @@ function isCandidateUsable(candidate, ctx) {
 * Resolve a tier to the best available concrete target. Prefers the tier's
 * first-choice (Claude) candidate; if its engine is missing or unkeyed, walks
 * the cross-engine equivalence ladder and returns the first usable equivalent,
-* tagging the result `fellback` with the original tier in `from`. Returns
-* `undefined` only when NOTHING in the chain is usable — the caller then skips
-* the work or surfaces a "no AI engine available" message.
+* tagging the result `fell-over` with the original tier in `requestedTier`.
+* Returns `undefined` only when NOTHING in the chain is usable — the caller
+* then skips the work or surfaces a "no AI engine available" message.
 */
 function resolveTier(tier, ctx) {
 	const chain = TIER_CHAINS[tier] ?? TIER_CHAINS.sonnet;
@@ -144,13 +144,28 @@ function resolveTier(tier, ctx) {
 			reason: "preferred"
 		} : {
 			candidate,
-			from: tier,
-			reason: "fellback"
+			requestedTier: tier,
+			reason: "fell-over"
 		};
 	}
 }
+/**
+* The ORDERED list of usable candidates for a tier — the runtime-fallback
+* sequence. `resolveTier` returns only the single best pick (good when you
+* trust it will work); this returns every usable candidate in preference order
+* so a caller can advance to the next when one fails AT RUNTIME — e.g. the
+* preferred model is installed + keyed (so it passes `isCandidateUsable`) yet
+* its CLI reports it offline at spawn ("Claude Fable 5 is currently
+* unavailable"). The static check can't predict an outage; only the spawn
+* result can, so the caller walks this list until a spawn returns without the
+* `unavailable` flag. Empty when nothing in the chain is usable.
+*/
+function usableTierCandidates(tier, ctx) {
+	return (TIER_CHAINS[tier] ?? TIER_CHAINS.sonnet).filter((c) => isCandidateUsable(c, ctx));
+}
 
 //#endregion
 exports.TIER_CHAINS = TIER_CHAINS;
 exports.isCandidateUsable = isCandidateUsable;
-exports.resolveTier = resolveTier;
+exports.resolveTier = resolveTier;
+exports.usableTierCandidates = usableTierCandidates;

package/dist/ai/spawn.d.mts

@@ -11,6 +11,8 @@
  *   SDK installs. Retry: 3 attempts on overload (HTTP 529 / "Overloaded"), exp.
  *   backoff (5s / 15s / 45s). Each retry is a fresh subprocess.
  */
+import type { RouteContext, TierCandidate } from './route.mts';
+import type { AiTier } from './tier.mts';
 import type { AgentSpawnResult, AiAgentName, SpawnAiAgentOptions } from './types.mts';
 export declare function backoffFor(attempt: number): number;
 /**
@@ -31,6 +33,7 @@ export declare function buildArgs(agent: AiAgentName, options: SpawnAiAgentOptio
  * shapes (`fable`, `claude-fable-5`, `mythos`, `claude-mythos-5`).
  */
 export declare function isAdaptiveOnlyModel(model: string): boolean;
+export declare function isModelUnavailable(stdout: string, stderr: string): boolean;
 export declare function isOverloaded(stdout: string, stderr: string): boolean;
 export declare function pickAgent(requested: AiAgentName | undefined, cwd: string): Promise<AiAgentName>;
 /**
@@ -55,3 +58,32 @@ export declare function pickAgent(requested: AiAgentName | undefined, cwd: strin
  *   is requested, when none of the known agents are on PATH).
  */
 export declare function spawnAiAgent(options: SpawnAiAgentOptions): Promise<AgentSpawnResult>;
+/**
+ * Result of a tier spawn that may have fallen over one or more offline models.
+ * `result` is the spawn that actually ran (the first whose model was not
+ * `unavailable`, or the last attempt if every candidate was down). `candidate`
+ * is the engine/model that produced it. `fellOver` lists the candidates that
+ * reported their model offline before this one — empty on a first-try success.
+ */
+export interface TierSpawnResult {
+    readonly candidate: TierCandidate;
+    readonly fellOver: readonly TierCandidate[];
+    readonly result: AgentSpawnResult;
+}
+/**
+ * Spawn a tier's work, automatically FALLING OVER to the next agent when a
+ * model is offline. Walks the tier's usable candidates (Claude → Codex →
+ * open-weight) in order; if a spawn comes back with `unavailable` (the model is
+ * down or gated — e.g. "Claude Fable 5 is currently unavailable"), it advances
+ * to the next candidate instead of failing. This is the runtime complement to
+ * `route.mts`'s static availability check: that check can't predict an outage,
+ * so the live spawn result drives the fallback.
+ *
+ * Returns the first non-`unavailable` spawn (success OR a genuine work failure
+ * on a model that WAS reachable — a real failure shouldn't silently retry on a
+ * weaker model). If every candidate is offline, returns the last attempt with
+ * its `unavailable` flag set, so the caller can report "all models down".
+ * Throws only when the tier has no usable candidate at all (nothing installed +
+ * keyed) — same contract as `resolveTier` returning undefined.
+ */
+export declare function spawnTierWithFallback(tier: AiTier, ctx: RouteContext, options: Omit<SpawnAiAgentOptions, 'agent' | 'effort' | 'model'>): Promise<TierSpawnResult>;

package/dist/ai/spawn.js

@@ -9,6 +9,7 @@ const require_process_spawn_errors = require('../process/spawn/errors.js');
 const require_process_spawn_child = require('../process/spawn/child.js');
 const require_ai_discover = require('./discover.js');
 const require_primordials_promise = require('../primordials/promise.js');
+const require_ai_route = require('./route.js');
 
 //#region src/ai/spawn.mts
 /**
@@ -113,6 +114,45 @@ function buildArgs(agent, options) {
 function isAdaptiveOnlyModel(model) {
 	return /\b(?:fable|mythos)\b/i.test(model) || /claude-(?:fable|mythos)/i.test(model);
 }
+const MODEL_UNAVAILABLE_PHRASES = [
+	"access denied",
+	"currently unavailable",
+	"forbidden",
+	"have access",
+	"is unavailable",
+	"isn’t available",
+	"isn't available",
+	"may not exist",
+	"no access to",
+	"no such model",
+	"not authorized",
+	"not authorised",
+	"not available",
+	"permission denied",
+	"permission_denied",
+	"temporarily unavailable",
+	"unauthorized",
+	"unauthorised"
+];
+const MODEL_EXISTENCE_PHRASES = [
+	"does not exist",
+	"doesn't exist",
+	"no such",
+	"not exist",
+	"not found",
+	"unavailable",
+	"unknown",
+	"unreachable"
+];
+function isModelUnavailable(stdout, stderr) {
+	const text = `${stdout}\n${stderr}`.toLowerCase();
+	for (let i = 0, { length } = MODEL_UNAVAILABLE_PHRASES; i < length; i += 1) if (text.includes(MODEL_UNAVAILABLE_PHRASES[i])) return true;
+	if (/\bmodel[_-]?not[_-]?found\b/i.test(text) || /\bapi error:\s*(?:403|404)\b/i.test(text)) return true;
+	if (text.includes("model")) {
+		for (let i = 0, { length } = MODEL_EXISTENCE_PHRASES; i < length; i += 1) if (text.includes(MODEL_EXISTENCE_PHRASES[i])) return true;
+	}
+	return false;
+}
 function isOverloaded(stdout, stderr) {
 	const re = /API Error: 529|Overloaded/i;
 	return re.test(stdout) || re.test(stderr);
@@ -200,7 +240,54 @@ async function spawnAiAgent(options) {
 		exitCode,
 		overloaded: isOverloaded(stdout, stderr),
 		stderr,
-		stdout
+		stdout,
+		unavailable: isModelUnavailable(stdout, stderr)
+	};
+}
+/**
+* Spawn a tier's work, automatically FALLING OVER to the next agent when a
+* model is offline. Walks the tier's usable candidates (Claude → Codex →
+* open-weight) in order; if a spawn comes back with `unavailable` (the model is
+* down or gated — e.g. "Claude Fable 5 is currently unavailable"), it advances
+* to the next candidate instead of failing. This is the runtime complement to
+* `route.mts`'s static availability check: that check can't predict an outage,
+* so the live spawn result drives the fallback.
+*
+* Returns the first non-`unavailable` spawn (success OR a genuine work failure
+* on a model that WAS reachable — a real failure shouldn't silently retry on a
+* weaker model). If every candidate is offline, returns the last attempt with
+* its `unavailable` flag set, so the caller can report "all models down".
+* Throws only when the tier has no usable candidate at all (nothing installed +
+* keyed) — same contract as `resolveTier` returning undefined.
+*/
+async function spawnTierWithFallback(tier, ctx, options) {
+	const candidates = require_ai_route.usableTierCandidates(tier, ctx);
+	if (candidates.length === 0) throw new require_primordials_error.ErrorCtor(`spawnTierWithFallback: no usable agent for tier "${tier}". No candidate engine is both installed and keyed (checked: ${candidates.length}). Install/authenticate one of the tier's engines, or pick a different tier.`);
+	const fellOver = [];
+	let last;
+	for (let i = 0, { length } = candidates; i < length; i += 1) {
+		const candidate = candidates[i];
+		const result = await spawnAiAgent({
+			...options,
+			agent: candidate.engine,
+			effort: candidate.effort,
+			model: candidate.model
+		});
+		last = {
+			candidate,
+			result
+		};
+		if (!result.unavailable) return {
+			candidate,
+			fellOver,
+			result
+		};
+		fellOver.push(candidate);
+	}
+	return {
+		candidate: last.candidate,
+		fellOver: fellOver.slice(0, -1),
+		result: last.result
 	};
 }
 
@@ -208,6 +295,8 @@ async function spawnAiAgent(options) {
 exports.backoffFor = backoffFor;
 exports.buildArgs = buildArgs;
 exports.isAdaptiveOnlyModel = isAdaptiveOnlyModel;
+exports.isModelUnavailable = isModelUnavailable;
 exports.isOverloaded = isOverloaded;
 exports.pickAgent = pickAgent;
-exports.spawnAiAgent = spawnAiAgent;
+exports.spawnAiAgent = spawnAiAgent;
+exports.spawnTierWithFallback = spawnTierWithFallback;

package/dist/ai/types.d.mts

@@ -56,6 +56,16 @@ export interface AgentSpawnResult {
     readonly overloaded: boolean;
     readonly stderr: string;
     readonly stdout: string;
+    /**
+     * True when the selected MODEL could not serve the request — it is offline
+     * (e.g. "Claude Fable 5 is currently unavailable") or gated/absent for this
+     * account ("issue with the selected model … may not exist or you may not have
+     * access"). Distinct from `overloaded`: the model is not coming back within a
+     * retry window, so the right response is to FALL OVER to the next agent in
+     * the tier chain rather than retry the same one. Both surface as a non-zero
+     * `exitCode`; this flag is how a caller knows to route elsewhere.
+     */
+    readonly unavailable: boolean;
 }
 /**
  * Inputs to a single agent spawn.