@socketsecurity/lib 6.0.8 → 6.0.10

package/CHANGELOG.md

@@ -5,6 +5,34 @@ 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.10](https://github.com/SocketDev/socket-lib/releases/tag/v6.0.10) - 2026-07-13
+
+### Fixed
+
+- **`stdio/footer`** — lazy-load colors so import survives --build-snapshot
+
+## [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/README.md

@@ -1,11 +1,10 @@
 # @socketsecurity/lib
 
-[![Socket Badge](https://socket.dev/api/badge/npm/package/@socketsecurity/lib)](https://socket.dev/npm/package/@socketsecurity/lib)
-[![CI](https://github.com/SocketDev/socket-lib/actions/workflows/ci.yml/badge.svg)](https://github.com/SocketDev/socket-lib/actions/workflows/ci.yml)
-![Coverage](https://img.shields.io/badge/coverage-99%25-brightgreen)
+<a href="https://socket.dev/npm/package/@socketsecurity/lib"><img src="https://socket.dev/api/badge/npm/package/@socketsecurity/lib" alt="Socket Badge" height="20"></a>
+![Coverage](assets/repo/coverage.svg)
 
-[![Follow @SocketSecurity](https://img.shields.io/twitter/follow/SocketSecurity?style=social)](https://twitter.com/SocketSecurity)
-[![Follow @socket.dev on Bluesky](https://img.shields.io/badge/Follow-@socket.dev-1DA1F2?style=social&logo=bluesky)](https://bsky.app/profile/socket.dev)
+[![Follow @SocketSecurity](assets/fleet/badge-follow-x.svg)](https://twitter.com/SocketSecurity)
+[![Follow @socket.dev on Bluesky](assets/fleet/badge-follow-bluesky.svg)](https://bsky.app/profile/socket.dev)
 
 Core utilities for [Socket.dev](https://socket.dev/) tools: file system, processes, HTTP, env detection, logging, spinners, and more. Tree-shakeable, TypeScript-first, cross-platform.
 
@@ -22,8 +21,8 @@ pnpm add @socketsecurity/lib
 ## Usage
 
 ```typescript
-import { Spinner } from '@socketsecurity/lib/spinner'
-import { readJson } from '@socketsecurity/lib/fs'
+import { Spinner } from '@socketsecurity/lib/spinner/spinner'
+import { readJson } from '@socketsecurity/lib/fs/read-json'
 
 const spinner = Spinner({ text: 'Loading…' })
 spinner.start()
@@ -34,9 +33,9 @@ spinner.successAndStop(`Loaded ${pkg.name}@${pkg.version}`)
 Every export lives under a subpath — pick what you need:
 
 ```typescript
-import { spawn } from '@socketsecurity/lib/spawn'
+import { spawn } from '@socketsecurity/lib/process/spawn/child'
 import { httpJson } from '@socketsecurity/lib/http-request'
-import { safeDelete } from '@socketsecurity/lib/fs'
+import { safeDelete } from '@socketsecurity/lib/fs/safe'
 ```
 
 Start with the [API reference](./docs/api.md) — every subpath export with a one-line description.

package/dist/abort/signal.d.ts

@@ -19,7 +19,7 @@ export declare function createCompositeAbortSignal(...signals: Array<AbortSignal
  * @example
  *   ;```typescript
  *   const signal = createTimeoutSignal(5000) // aborts after 5 seconds
- *   fetch('https://example.com', { signal })
+ *   httpJson(url, { signal })
  *   ```
  *
  * @throws {TypeError} If `ms` is not a number, is NaN, is not finite, or is not

package/dist/abort/signal.js

@@ -40,7 +40,7 @@ function createCompositeAbortSignal(...signals) {
 * @example
 *   ;```typescript
 *   const signal = createTimeoutSignal(5000) // aborts after 5 seconds
-*   fetch('https://example.com', { signal })
+*   httpJson(url, { signal })
 *   ```
 *
 * @throws {TypeError} If `ms` is not a number, is NaN, is not finite, or is not

package/dist/ai/agent-context.d.mts

@@ -22,7 +22,7 @@
  *     the human-authored AGENTS.md. So `agentPaths(...).memoryDir` is defined
  *     only for `claude`; for the others it is `undefined` (there is no memory
  *     dir to point at), and the shared cross-tool memory surface is the
- *     committed AGENTS.md (which the fleet symlinks to CLAUDE.md).
+ *     committed AGENTS.md (which Socket symlinks to CLAUDE.md).
  */
 import type { AiAgentName } from './types.mts';
 /**

package/dist/ai/agent-context.js

@@ -6,6 +6,7 @@ const require_constants_platform = require('../constants/platform.js');
 const require_env_rewire = require('../env/rewire.js');
 const require_env_home = require('../env/home.js');
 const require_env_xdg = require('../env/xdg.js');
+const require_paths_normalize = require('../paths/normalize.js');
 let node_path = require("node:path");
 node_path = require_runtime.__toESM(node_path, 1);
 
@@ -34,7 +35,7 @@ node_path = require_runtime.__toESM(node_path, 1);
 *     the human-authored AGENTS.md. So `agentPaths(...).memoryDir` is defined
 *     only for `claude`; for the others it is `undefined` (there is no memory
 *     dir to point at), and the shared cross-tool memory surface is the
-*     committed AGENTS.md (which the fleet symlinks to CLAUDE.md).
+*     committed AGENTS.md (which Socket symlinks to CLAUDE.md).
 */
 function agentFromAiAgentEnv(value) {
 	const lower = value.toLowerCase();
@@ -76,7 +77,7 @@ function agentPaths(agent, options) {
 			return {
 				agent,
 				configDir,
-				memoryDir: cwd ? node_path.default.join(configDir, "projects", cwd.replace(/[/\\]/g, "-"), "memory") : void 0
+				memoryDir: cwd ? node_path.default.join(configDir, "projects", require_paths_normalize.normalizePath(cwd).replace(/\//g, "-"), "memory") : void 0
 			};
 		}
 		case "codex": return {

package/dist/ai/backends.d.mts

@@ -1,5 +1,5 @@
 /**
- * @file Multi-agent CLI backend registry + role routing. The fleet's review /
+ * @file Multi-agent CLI backend registry + role routing. Socket's review /
  *   scan / fix skills delegate work to whichever agent CLIs are installed
  *   (`codex`, `claude`, `kimi`, `opencode`), falling back through a per-role
  *   preference order and skipping a pass when nothing usable is present. Before
@@ -22,7 +22,7 @@
  *   attribution accurate.
  */
 /**
- * A CLI backend the fleet can delegate a pass to.
+ * A CLI backend Socket can delegate a pass to.
  */
 export type BackendName = 'claude' | 'codex' | 'kimi' | 'opencode';
 /**
@@ -73,7 +73,7 @@ export interface ResolveBackendOptions {
     readonly override?: BackendName | undefined;
 }
 /**
- * Resolve which backend runs a pass, encoding the fleet detection policy
+ * Resolve which backend runs a pass, encoding Socket's detection policy
  * (`_shared/multi-agent-backends.md`): an installed explicit override wins;
  * else the first installed non-hybrid entry in the preference order; else
  * nothing (skip the pass). Pure — returns the decision + why, never logs. An

package/dist/ai/backends.js

@@ -6,7 +6,7 @@ const require_ai_spawn = require('./spawn.js');
 
 //#region src/ai/backends.mts
 /**
-* @file Multi-agent CLI backend registry + role routing. The fleet's review /
+* @file Multi-agent CLI backend registry + role routing. Socket's review /
 *   scan / fix skills delegate work to whichever agent CLIs are installed
 *   (`codex`, `claude`, `kimi`, `opencode`), falling back through a per-role
 *   preference order and skipping a pass when nothing usable is present. Before
@@ -131,7 +131,7 @@ async function isCommandAvailable(bin) {
 	return await require_bin_which.which(bin) !== null;
 }
 /**
-* Resolve which backend runs a pass, encoding the fleet detection policy
+* Resolve which backend runs a pass, encoding Socket's detection policy
 * (`_shared/multi-agent-backends.md`): an installed explicit override wins;
 * else the first installed non-hybrid entry in the preference order; else
 * nothing (skip the pass). Pure — returns the decision + why, never logs. An

package/dist/ai/billing-context.d.mts

@@ -0,0 +1,74 @@
+/**
+ * @file Build a `BillingContext` for the route-heuristic WITHOUT privileged
+ *   lookups. A normal user has no Admin key (`sk-ant-admin01-`), so we cannot
+ *   read org spend / quota — the Anthropic Cost API is admin-gated — and that
+ *   is an accepted limitation, not something to engineer around. So this layer
+ *   does NO network call and NO privileged probe. It uses only what a user
+ *   actually has: which provider credentials resolve (the same env → keychain
+ *   check that builds `RouteContext.keyed`, non-admin), tags each with its
+ *   INHERENT billing kind (a metered API, a flat-rate plan, a subscription seat
+ *   — the provider's nature, overridable by config), and leaves `headroom`
+ *   undefined. Undefined headroom means the heuristic routes REACTIVELY: it
+ *   falls over on a 429 / quota error at spawn time (`isQuotaExhausted` in
+ *   `spawn.mts`), rather than predicting a cap it has no privilege to read. A
+ *   caller that DOES have a non-privileged quota endpoint (e.g. Synthetic
+ *   `/v2/quotas` with the ordinary key) may pass best-effort `headroom` in —
+ *   but nothing here requires it, and no privileged reader is built or wired.
+ */
+import type { CredentialProvider } from './credentials.mts';
+import type { BillingContext, BillingHeadroom, BillingKind, RoutingEnv } from './route-heuristic.mts';
+/**
+ * Inherent billing model per provider — the provider's NATURE, not anyone's
+ * account or limit. A metered pay-per-token API (`anthropic` with an API key,
+ * `fireworks`, `xai`), a flat-rate plan (`synthetic`), or a subscription seat
+ * (`openai` via a ChatGPT/Codex seat). These are DEFAULTS only: a caller
+ * overrides per provider via the `kinds` option — e.g. a user whose Anthropic
+ * access is a Claude Max seat (no API key) marks `anthropic` as `subscription`.
+ * No dollar figures here; only the kind, which decides dollars-vs-headroom.
+ */
+export declare const DEFAULT_PROVIDER_KIND: Readonly<Record<CredentialProvider, BillingKind>>;
+export interface BillingFromKeyedOptions {
+    readonly keyed: ReadonlySet<CredentialProvider>;
+    readonly kinds?: Readonly<Partial<Record<CredentialProvider, BillingKind>>> | undefined;
+    readonly headroom?: Readonly<Partial<Record<CredentialProvider, BillingHeadroom>>> | undefined;
+}
+/**
+ * Turn an already-probed set of keyed providers into a `BillingContext`,
+ * tagging each with its kind (config override → inherent default) and any
+ * caller-supplied best-effort headroom. Pure: no I/O, no privileged lookup. A
+ * provider with no known kind is skipped rather than given an undefined kind.
+ */
+export declare function billingFromKeyed(options: BillingFromKeyedOptions): BillingContext;
+/**
+ * Detect whether routing runs in locked-down CI (restricted to the secrets
+ * actually present, under the four-flag lockdown) or local dev (full freedom).
+ * CI when the standard `CI` env var is set; `local` otherwise.
+ */
+export declare function detectRoutingEnv(): RoutingEnv;
+export interface DiscoverBillingOptions {
+    readonly allowEnvOnly?: boolean | undefined;
+    readonly env?: RoutingEnv | undefined;
+    readonly headroom?: Readonly<Partial<Record<CredentialProvider, BillingHeadroom>>> | undefined;
+    readonly kinds?: Readonly<Partial<Record<CredentialProvider, BillingKind>>> | undefined;
+}
+/**
+ * Discover a `BillingContext` end-to-end with no privileged lookup: probe which
+ * provider credentials resolve (env → keychain, the non-admin check), then tag
+ * them via `billingFromKeyed`. Headroom defaults to undefined (reactive). In CI
+ * the credential probe is env-only (no keychain prompt); locally it allows the
+ * keychain. Convenience over calling `discoverKeyedProviders` +
+ * `billingFromKeyed`.
+ *
+ * @unused No internal or Socket consumers (exercised only by its unit tests).
+ */
+export declare function discoverBilling(options?: DiscoverBillingOptions | undefined): Promise<BillingContext>;
+export interface DiscoverKeyedProvidersOptions {
+    readonly allowEnvOnly?: boolean | undefined;
+}
+/**
+ * The set of providers with a resolvable credential, probed via the same
+ * non-admin env → keychain resolver `RouteContext.keyed` uses. No network, no
+ * privilege. Pass `allowEnvOnly: true` in headless contexts to skip the
+ * keychain entirely.
+ */
+export declare function discoverKeyedProviders(options?: DiscoverKeyedProvidersOptions | undefined): Promise<Set<CredentialProvider>>;

package/dist/ai/billing-context.js

@@ -0,0 +1,129 @@
+"use strict";
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_primordials_object = require('../primordials/object.js');
+const require_env_rewire = require('../env/rewire.js');
+const require_ai_credentials = require('./credentials.js');
+
+//#region src/ai/billing-context.mts
+/**
+* @file Build a `BillingContext` for the route-heuristic WITHOUT privileged
+*   lookups. A normal user has no Admin key (`sk-ant-admin01-`), so we cannot
+*   read org spend / quota — the Anthropic Cost API is admin-gated — and that
+*   is an accepted limitation, not something to engineer around. So this layer
+*   does NO network call and NO privileged probe. It uses only what a user
+*   actually has: which provider credentials resolve (the same env → keychain
+*   check that builds `RouteContext.keyed`, non-admin), tags each with its
+*   INHERENT billing kind (a metered API, a flat-rate plan, a subscription seat
+*   — the provider's nature, overridable by config), and leaves `headroom`
+*   undefined. Undefined headroom means the heuristic routes REACTIVELY: it
+*   falls over on a 429 / quota error at spawn time (`isQuotaExhausted` in
+*   `spawn.mts`), rather than predicting a cap it has no privilege to read. A
+*   caller that DOES have a non-privileged quota endpoint (e.g. Synthetic
+*   `/v2/quotas` with the ordinary key) may pass best-effort `headroom` in —
+*   but nothing here requires it, and no privileged reader is built or wired.
+*/
+/**
+* Inherent billing model per provider — the provider's NATURE, not anyone's
+* account or limit. A metered pay-per-token API (`anthropic` with an API key,
+* `fireworks`, `xai`), a flat-rate plan (`synthetic`), or a subscription seat
+* (`openai` via a ChatGPT/Codex seat). These are DEFAULTS only: a caller
+* overrides per provider via the `kinds` option — e.g. a user whose Anthropic
+* access is a Claude Max seat (no API key) marks `anthropic` as `subscription`.
+* No dollar figures here; only the kind, which decides dollars-vs-headroom.
+*/
+const DEFAULT_PROVIDER_KIND = {
+	__proto__: null,
+	anthropic: "metered",
+	fireworks: "metered",
+	openai: "subscription",
+	synthetic: "flat-rate",
+	xai: "metered"
+};
+/**
+* Turn an already-probed set of keyed providers into a `BillingContext`,
+* tagging each with its kind (config override → inherent default) and any
+* caller-supplied best-effort headroom. Pure: no I/O, no privileged lookup. A
+* provider with no known kind is skipped rather than given an undefined kind.
+*/
+function billingFromKeyed(options) {
+	const opts = {
+		__proto__: null,
+		...options
+	};
+	const out = { __proto__: null };
+	for (const provider of opts.keyed) {
+		const kind = opts.kinds?.[provider] ?? DEFAULT_PROVIDER_KIND[provider];
+		if (!kind) continue;
+		const headroom = opts.headroom?.[provider];
+		out[provider] = headroom ? {
+			headroom,
+			kind,
+			provider
+		} : {
+			kind,
+			provider
+		};
+	}
+	return out;
+}
+/**
+* Detect whether routing runs in locked-down CI (restricted to the secrets
+* actually present, under the four-flag lockdown) or local dev (full freedom).
+* CI when the standard `CI` env var is set; `local` otherwise.
+*/
+function detectRoutingEnv() {
+	return require_env_rewire.getEnvValue("CI") ? "ci" : "local";
+}
+/**
+* Discover a `BillingContext` end-to-end with no privileged lookup: probe which
+* provider credentials resolve (env → keychain, the non-admin check), then tag
+* them via `billingFromKeyed`. Headroom defaults to undefined (reactive). In CI
+* the credential probe is env-only (no keychain prompt); locally it allows the
+* keychain. Convenience over calling `discoverKeyedProviders` +
+* `billingFromKeyed`.
+*
+* @unused No internal or Socket consumers (exercised only by its unit tests).
+*/
+async function discoverBilling(options) {
+	const opts = {
+		__proto__: null,
+		...options
+	};
+	const env = opts.env ?? detectRoutingEnv();
+	const keyed = await discoverKeyedProviders({ allowEnvOnly: opts.allowEnvOnly ?? env === "ci" });
+	return billingFromKeyed({
+		headroom: opts.headroom,
+		keyed,
+		kinds: opts.kinds
+	});
+}
+/**
+* The set of providers with a resolvable credential, probed via the same
+* non-admin env → keychain resolver `RouteContext.keyed` uses. No network, no
+* privilege. Pass `allowEnvOnly: true` in headless contexts to skip the
+* keychain entirely.
+*/
+async function discoverKeyedProviders(options) {
+	const opts = {
+		__proto__: null,
+		...options
+	};
+	const providers = require_primordials_object.ObjectKeys(require_ai_credentials.PROVIDER_CREDENTIALS);
+	const keyed = /* @__PURE__ */ new Set();
+	for (let i = 0, { length } = providers; i < length; i += 1) {
+		const provider = providers[i];
+		if (await require_ai_credentials.resolveProviderCredential({
+			allowEnvOnly: opts.allowEnvOnly,
+			provider
+		})) keyed.add(provider);
+	}
+	return keyed;
+}
+
+//#endregion
+exports.DEFAULT_PROVIDER_KIND = DEFAULT_PROVIDER_KIND;
+exports.billingFromKeyed = billingFromKeyed;
+exports.detectRoutingEnv = detectRoutingEnv;
+exports.discoverBilling = discoverBilling;
+exports.discoverKeyedProviders = discoverKeyedProviders;

package/dist/ai/credentials.d.mts

@@ -14,11 +14,10 @@
  *   `undefined` immediately instead of triggering a keychain auth prompt. CI
  *   sets the token as a GH-secret env var (e.g. `ANTHROPIC_API_KEY`); the same
  *   `resolveProviderCredential` call reads it there with no keychain. proteus
- *   hook-point: the forthcoming biometric credential daemon
- *   (`.claude/plans/proteus-credential-broker.md`) slots in as a layer between
- *   the env check and the keychain read inside `resolve()`'s implementation —
- *   call sites here do not change when it lands (resolver decision #4 in that
- *   plan). This module is the stable seam.
+ *   hook-point: the forthcoming biometric credential daemon slots in as a
+ *   layer between the env check and the keychain read inside `resolve()`'s
+ *   implementation — call sites here do not change when it lands. This module
+ *   is the stable seam.
  */
 /**
  * A provider whose credential this module can resolve: the HTTP providers
@@ -31,6 +30,19 @@ export interface ProviderCredentialSpec {
     readonly keychainService: string;
 }
 export declare const PROVIDER_CREDENTIALS: Readonly<Record<CredentialProvider, ProviderCredentialSpec>>;
+export interface DeleteProviderCredentialOptions {
+    readonly provider: CredentialProvider;
+}
+/**
+ * Remove a provider's stored credential from the OS keychain — the same
+ * `{ service, account }` slot `resolveProviderCredential` reads. Returns
+ * `'removed'` when a value was deleted, `'absent'` when none was stored (or the
+ * platform has no keychain backend — delete degrades to a no-op rather than
+ * throwing, since "nothing to remove" is the same outcome either way).
+ *
+ * @unused No internal or Socket consumers (exercised only by its unit tests).
+ */
+export declare function deleteProviderCredential(options: DeleteProviderCredentialOptions): Promise<'absent' | 'removed'>;
 /**
  * True when `value` names a provider with a resolvable credential.
  */
@@ -47,3 +59,25 @@ export interface ResolveProviderCredentialOptions {
  * source has it (the caller decides whether that's fatal).
  */
 export declare function resolveProviderCredential(options: ResolveProviderCredentialOptions): Promise<string | undefined>;
+export interface WriteProviderCredentialOptions {
+    readonly provider: CredentialProvider;
+    readonly value: string;
+}
+/**
+ * Persist a provider's bearer token to the OS keychain — the SAME `{ service,
+ * account }` slot `resolveProviderCredential` reads (account == `tokenEnv`,
+ * service == the Socket-uniform `socketsecurity` scope), so a written token
+ * resolves on the next read without an env var.
+ *
+ * Keychain ONLY — this never writes a shell-rc export. That matters most for
+ * anthropic: a live `ANTHROPIC_API_KEY` env var overrides a Claude Max-seat
+ * OAuth session and silently flips the user to metered billing, so its token
+ * must live only in the keychain (read on demand), never exported. A setup
+ * wizard that rc-exports `FIREWORKS_API_KEY`/`SYNTHETIC_API_KEY` for
+ * convenience must still route anthropic here, keychain-only.
+ *
+ * Returns `'written'` | `'unchanged'` (idempotent — an identical stored value
+ * is a no-op). Throws when the OS has no keychain backend; a caller that wants
+ * to degrade gracefully should check `getBackendAvailability()` first.
+ */
+export declare function writeProviderCredential(options: WriteProviderCredentialOptions): Promise<'unchanged' | 'written'>;

package/dist/ai/credentials.js

@@ -1,6 +1,7 @@
 "use strict";
 /* Socket Lib - Built with rolldown */
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_secrets_keychain = require('../secrets/keychain.js');
 const require_secrets_find = require('../secrets/find.js');
 
 //#region src/ai/credentials.mts
@@ -20,11 +21,10 @@ const require_secrets_find = require('../secrets/find.js');
 *   `undefined` immediately instead of triggering a keychain auth prompt. CI
 *   sets the token as a GH-secret env var (e.g. `ANTHROPIC_API_KEY`); the same
 *   `resolveProviderCredential` call reads it there with no keychain. proteus
-*   hook-point: the forthcoming biometric credential daemon
-*   (`.claude/plans/proteus-credential-broker.md`) slots in as a layer between
-*   the env check and the keychain read inside `resolve()`'s implementation —
-*   call sites here do not change when it lands (resolver decision #4 in that
-*   plan). This module is the stable seam.
+*   hook-point: the forthcoming biometric credential daemon slots in as a
+*   layer between the env check and the keychain read inside `resolve()`'s
+*   implementation — call sites here do not change when it lands. This module
+*   is the stable seam.
 */
 const PROVIDER_CREDENTIALS = {
 	__proto__: null,
@@ -50,6 +50,27 @@ const PROVIDER_CREDENTIALS = {
 	}
 };
 /**
+* Remove a provider's stored credential from the OS keychain — the same
+* `{ service, account }` slot `resolveProviderCredential` reads. Returns
+* `'removed'` when a value was deleted, `'absent'` when none was stored (or the
+* platform has no keychain backend — delete degrades to a no-op rather than
+* throwing, since "nothing to remove" is the same outcome either way).
+*
+* @unused No internal or Socket consumers (exercised only by its unit tests).
+*/
+async function deleteProviderCredential(options) {
+	const opts = {
+		__proto__: null,
+		...options
+	};
+	const spec = PROVIDER_CREDENTIALS[opts.provider];
+	if (!spec) return "absent";
+	return await require_secrets_keychain.deleteSecret({
+		account: spec.tokenEnv,
+		service: spec.keychainService
+	});
+}
+/**
 * True when `value` names a provider with a resolvable credential.
 */
 function isCredentialProvider(value) {
@@ -75,8 +96,42 @@ async function resolveProviderCredential(options) {
 		service: spec.keychainService
 	}))?.value;
 }
+/**
+* Persist a provider's bearer token to the OS keychain — the SAME `{ service,
+* account }` slot `resolveProviderCredential` reads (account == `tokenEnv`,
+* service == the Socket-uniform `socketsecurity` scope), so a written token
+* resolves on the next read without an env var.
+*
+* Keychain ONLY — this never writes a shell-rc export. That matters most for
+* anthropic: a live `ANTHROPIC_API_KEY` env var overrides a Claude Max-seat
+* OAuth session and silently flips the user to metered billing, so its token
+* must live only in the keychain (read on demand), never exported. A setup
+* wizard that rc-exports `FIREWORKS_API_KEY`/`SYNTHETIC_API_KEY` for
+* convenience must still route anthropic here, keychain-only.
+*
+* Returns `'written'` | `'unchanged'` (idempotent — an identical stored value
+* is a no-op). Throws when the OS has no keychain backend; a caller that wants
+* to degrade gracefully should check `getBackendAvailability()` first.
+*/
+async function writeProviderCredential(options) {
+	const opts = {
+		__proto__: null,
+		...options
+	};
+	const spec = PROVIDER_CREDENTIALS[opts.provider];
+	if (!spec) throw new Error(`writeProviderCredential: unknown provider "${opts.provider}".`);
+	const backend = require_secrets_keychain.getBackendAvailability();
+	if (!backend.available) throw new Error(`writeProviderCredential: no OS keychain backend (${backend.toolName}) available to store the ${opts.provider} credential.` + (backend.installHint ? ` ${backend.installHint}` : ""));
+	return await require_secrets_keychain.writeSecret({
+		account: spec.tokenEnv,
+		service: spec.keychainService,
+		value: opts.value
+	});
+}
 
 //#endregion
 exports.PROVIDER_CREDENTIALS = PROVIDER_CREDENTIALS;
+exports.deleteProviderCredential = deleteProviderCredential;
 exports.isCredentialProvider = isCredentialProvider;
-exports.resolveProviderCredential = resolveProviderCredential;
+exports.resolveProviderCredential = resolveProviderCredential;
+exports.writeProviderCredential = writeProviderCredential;

package/dist/ai/discover.d.mts

@@ -43,12 +43,16 @@ export declare function discoverFresh(): DiscoveredAgents;
  *
  * Useful in fast paths where the caller has already populated the cache and
  * just wants to read it back.
+ *
+ * @unused No internal or Socket consumers (exercised only by its unit tests).
  */
 export declare function getDiscoveredAiAgents(): DiscoveredAgents | undefined;
 export declare function readDiskCache(cachePath: string): DiscoveredAgents | undefined;
 /**
  * Reset the in-process cache. Tests use this; production callers shouldn't need
  * it (use `refresh: true` on discoverAiAgents()).
+ *
+ * @unused No internal or Socket consumers (exercised only by its unit tests).
  */
 export declare function resetAiAgentDiscoveryCache(): void;
 export declare function writeDiskCache(cachePath: string, agents: DiscoveredAgents): Promise<void>;

package/dist/ai/discover.js

@@ -87,6 +87,8 @@ function discoverFresh() {
 *
 * Useful in fast paths where the caller has already populated the cache and
 * just wants to read it back.
+*
+* @unused No internal or Socket consumers (exercised only by its unit tests).
 */
 function getDiscoveredAiAgents() {
 	return inProcessCache;
@@ -104,6 +106,8 @@ function readDiskCache(cachePath) {
 /**
 * Reset the in-process cache. Tests use this; production callers shouldn't need
 * it (use `refresh: true` on discoverAiAgents()).
+*
+* @unused No internal or Socket consumers (exercised only by its unit tests).
 */
 function resetAiAgentDiscoveryCache() {
 	inProcessCache = void 0;

package/dist/ai/exec.d.mts

@@ -3,7 +3,7 @@
  *   WHICH model produced it (`ai/backends`). The lib owns the INTERFACE plus
  *   the cheap built-in `real` runner (the host shell via lib `spawn`); a
  *   SANDBOXED runner is INJECTED by the caller, never imported here. That keeps
- *   the small-dist lib free of a heavy sandbox dependency — the fleet's sandbox
+ *   the small-dist lib free of a heavy sandbox dependency — Socket's sandbox
  *   of choice (`just-bash`, ~40MB incl. WASM) is owned by the wheelhouse hook /
  *   CI tooling and passed in, so a lib consumer that never sandboxes pays
  *   nothing. Layering: ExecRunner.run() — the injectable primitive (real |

package/dist/ai/exec.js

@@ -10,7 +10,7 @@ const require_process_spawn_child = require('../process/spawn/child.js');
 *   WHICH model produced it (`ai/backends`). The lib owns the INTERFACE plus
 *   the cheap built-in `real` runner (the host shell via lib `spawn`); a
 *   SANDBOXED runner is INJECTED by the caller, never imported here. That keeps
-*   the small-dist lib free of a heavy sandbox dependency — the fleet's sandbox
+*   the small-dist lib free of a heavy sandbox dependency — Socket's sandbox
 *   of choice (`just-bash`, ~40MB incl. WASM) is owned by the wheelhouse hook /
 *   CI tooling and passed in, so a lib consumer that never sandboxes pays
 *   nothing. Layering: ExecRunner.run() — the injectable primitive (real |

package/dist/ai/http.d.mts

@@ -4,7 +4,7 @@
  *   (`api.fireworks.ai`) and Synthetic (`api.synthetic.new`). The CLI path
  *   (`spawn.mts`) drives an interactive agent binary; this path is for a
  *   script/hook that needs a single completion from a model without an agent
- *   harness (the way the local OpenCode setup reaches GLM-5.1 / Kimi-K2.5). Why
+ *   harness (the way the local OpenCode setup reaches GLM-5.2 / Kimi-K2.6). Why
  *   a separate module from `spawn.mts`: those are different surfaces. A CLI
  *   agent gets tools + a permission mode + a working dir; an HTTP completion
  *   gets a prompt + a model + (optionally) a reasoning effort and returns text.
@@ -13,10 +13,10 @@
  *   function-calling surface — they're plain completions, so there's no agentic
  *   capability to constrain. The token is read from the env var the provider
  *   config names (`FIREWORKS_API_KEY` / `SYNTHETIC_API_KEY`), NEVER passed
- *   inline, and never logged — same token-hygiene rule as the rest of the
- *   fleet. A missing token throws with the exact env var to set. Wire format is
- *   the OpenAI Chat Completions API (`POST {baseUrl}/chat/completions`), which
- *   both providers implement.
+ *   inline, and never logged — same token-hygiene rule as the rest of Socket. A
+ *   missing token throws with the exact env var to set. Wire format is the
+ *   OpenAI Chat Completions API (`POST {baseUrl}/chat/completions`), which both
+ *   providers implement.
  */
 import type { AiEffort } from './types.mts';
 /**
@@ -47,8 +47,8 @@ export interface AiHttpCallOptions {
      */
     readonly provider: string | AiHttpProvider;
     /**
-     * The provider's model id (e.g. `accounts/fireworks/models/glm-5p1`,
-     * `hf:moonshotai/Kimi-K2.5`).
+     * The provider's model id (e.g. `accounts/fireworks/models/glm-5p2`,
+     * `hf:moonshotai/Kimi-K2.6`).
      */
     readonly model: string;
     /**
@@ -118,7 +118,7 @@ export declare function buildChatRequestBody(options: AiHttpCallOptions): string
  *   ;```ts
  *   const { text } = await callAiHttpModel({
  *     provider: 'fireworks',
- *     model: 'accounts/fireworks/models/glm-5p1',
+ *     model: 'accounts/fireworks/models/glm-5p2',
  *     prompt: 'Summarize this diff: …',
  *     effort: 'high',
  *   })