@socketsecurity/lib 6.0.7 → 6.0.9

package/dist/ai/subagent-status.js

@@ -0,0 +1,57 @@
+"use strict";
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_primordials_error = require('../primordials/error.js');
+
+//#region src/ai/subagent-status.mts
+/**
+* @file The terminal-status contract a delegated subagent returns to its
+*   orchestrator. Subagent-driven development depends on a SMALL, fixed status
+*   vocabulary so the orchestrator can route deterministically instead of
+*   parsing free-form prose: a subagent that "sort of finished but has a worry"
+*   must be distinguishable from one that is genuinely blocked, because they
+*   escalate differently. The four states and their escalation paths are the
+*   contract; `escalationFor` is the single place that maps a state to what the
+*   orchestrator does next. Encoding it as a typed union + map (rather than a
+*   doc convention) is the code-is-law surface: a stray status string fails the
+*   guard, and `agent-delegation.md` is checked against this union so the prose
+*   can't drift from the code.
+*/
+const ESCALATION = {
+	__proto__: null,
+	blocked: "escalate",
+	done: "advance",
+	"done-with-concerns": "surface",
+	"needs-context": "redispatch"
+};
+/**
+* The canonical status set, sorted, for callers that need to enumerate or
+* validate against the full vocabulary (the doc-parity check reads this).
+*/
+const SUBAGENT_STATUSES = [
+	"blocked",
+	"done",
+	"done-with-concerns",
+	"needs-context"
+];
+/**
+* Map a terminal status to the orchestrator action it requires. A status
+* outside the vocabulary is itself a contract violation, so this throws rather
+* than guessing — never force a retry on an unrecognized state.
+*/
+function escalationFor(status) {
+	const action = ESCALATION[status];
+	if (!action) throw new require_primordials_error.ErrorCtor(`escalationFor: unknown subagent status "${status}". Expected one of: ${SUBAGENT_STATUSES.join(", ")}. Return a status from the SubagentStatus contract.`);
+	return action;
+}
+/**
+* True when `value` names a status in the contract.
+*/
+function isSubagentStatus(value) {
+	return SUBAGENT_STATUSES.includes(value);
+}
+
+//#endregion
+exports.SUBAGENT_STATUSES = SUBAGENT_STATUSES;
+exports.escalationFor = escalationFor;
+exports.isSubagentStatus = isSubagentStatus;

package/dist/ai/tier.d.mts

@@ -0,0 +1,60 @@
+/**
+ * @file Canonical model + reasoning-effort ladder for AI orchestrators. The
+ *   fleet's AI-fix / AI-codify orchestrators pick a capability TIER per unit of
+ *   work (a lint rule, a hook, a doc edit) and resolve it to a concrete `{
+ *   model, effort }` pair. Before this module each orchestrator redefined the
+ *   same three-row table, so a model-generation bump (Sonnet 4.6 → 5.0, Opus
+ *   4.8 → 4.9) meant editing N files and risked drift. Import `AI_TIER` /
+ *   `tierToSpawn` here instead; a generation roll is then a single edit. The
+ *   mapping encodes the CLAUDE.md token-spend rule ("match model AND effort to
+ *   the job"): a cheap model left on the session's default effort still burns
+ *   reasoning a mechanical task never needs, and a premium model on low effort
+ *   under-thinks a hard one — so effort is pinned ALONGSIDE the model per
+ *   tier.
+ */
+import type { AiEffort } from './types.mts';
+/**
+ * The capability tiers, least → most capable. Orchestrators classify each unit
+ * of work into one of these (a regex-shaped rewrite → `haiku`; a caller-chain
+ * rewrite → `sonnet`; a module split / new-enforcer authoring → `opus`).
+ * `fable` is the apex escalation tier — reserve it for the hardest cases (a
+ * stuck compiler / native problem, planning + decomposition of a large task),
+ * never a first reach, and prefer to ask before selecting it. It is the most
+ * expensive model on the board (~2× opus, ~10× haiku output), so an
+ * orchestrator should pick the LEAST-capable tier that does the job and
+ * escalate to `fable` only after cheaper tiers fail.
+ */
+export type AiTier = 'fable' | 'haiku' | 'opus' | 'sonnet';
+/**
+ * Resolved spawn parameters for a tier — spread alongside an `AI_PROFILE` into
+ * a `spawnAiAgent` call (`{ ...AI_PROFILE.verify, ...tierToSpawn('opus'),
+ * prompt, cwd }`).
+ */
+export interface TierSpawn {
+    readonly effort: AiEffort;
+    readonly model: string;
+}
+/**
+ * Canonical tier → { model, effort }. The single source of truth for which
+ * Claude model + effort each tier runs. Bump here on a model generation roll;
+ * every orchestrator that imports this picks it up.
+ *
+ * - `haiku` / low — deterministic, regex-shaped rewrites (identifier rename,
+ *   null→undefined, single-token substitution).
+ * - `sonnet` / medium — control-flow / caller-chain reasoning (fetch→httpJson,
+ *   sync→async), a check script, a doc edit.
+ * - `opus` / high — real authoring / refactoring (module split, a brand-new hook
+ *   or lint rule with its test).
+ * - `fable` / xhigh — apex escalation only: a stuck compiler / native problem
+ *   after cheaper tiers fail, or planning + decomposition of a large task whose
+ *   chunks then run on cheaper tiers. Most expensive model on the board; never
+ *   a default.
+ */
+export declare const AI_TIER: Readonly<Record<AiTier, TierSpawn>>;
+/**
+ * Resolve a tier label to its `{ model, effort }` spawn pair. A convenience
+ * over indexing `AI_TIER` directly; returns the `sonnet` row for an unknown
+ * label so a caller that hands in a stray string degrades to the safe default
+ * rather than producing `undefined` model/effort.
+ */
+export declare function tierToSpawn(tier: AiTier): TierSpawn;

package/dist/ai/tier.js

@@ -0,0 +1,53 @@
+"use strict";
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+//#region src/ai/tier.mts
+/**
+* Canonical tier → { model, effort }. The single source of truth for which
+* Claude model + effort each tier runs. Bump here on a model generation roll;
+* every orchestrator that imports this picks it up.
+*
+* - `haiku` / low — deterministic, regex-shaped rewrites (identifier rename,
+*   null→undefined, single-token substitution).
+* - `sonnet` / medium — control-flow / caller-chain reasoning (fetch→httpJson,
+*   sync→async), a check script, a doc edit.
+* - `opus` / high — real authoring / refactoring (module split, a brand-new hook
+*   or lint rule with its test).
+* - `fable` / xhigh — apex escalation only: a stuck compiler / native problem
+*   after cheaper tiers fail, or planning + decomposition of a large task whose
+*   chunks then run on cheaper tiers. Most expensive model on the board; never
+*   a default.
+*/
+const AI_TIER = {
+	__proto__: null,
+	fable: {
+		effort: "xhigh",
+		model: "claude-fable-5"
+	},
+	haiku: {
+		effort: "low",
+		model: "claude-haiku-4-5"
+	},
+	opus: {
+		effort: "high",
+		model: "claude-opus-4-8"
+	},
+	sonnet: {
+		effort: "medium",
+		model: "claude-sonnet-4-6"
+	}
+};
+/**
+* Resolve a tier label to its `{ model, effort }` spawn pair. A convenience
+* over indexing `AI_TIER` directly; returns the `sonnet` row for an unknown
+* label so a caller that hands in a stray string degrades to the safe default
+* rather than producing `undefined` model/effort.
+*/
+function tierToSpawn(tier) {
+	return AI_TIER[tier] ?? AI_TIER.sonnet;
+}
+
+//#endregion
+exports.AI_TIER = AI_TIER;
+exports.tierToSpawn = tierToSpawn;

package/dist/ai/types.d.mts

@@ -26,8 +26,14 @@ export type AiAgentName = 'claude' | 'codex' | 'gemini' | 'opencode';
  */
 export type PermissionMode = 'acceptEdits' | 'dontAsk' | 'plan';
 /**
- * Reasoning-effort level for the agent session. Maps to the claude CLI
- * `--effort <level>` flag (claude-specific; other agents ignore it). Pair a
+ * Reasoning-effort level for the agent session. Two agents consume it, each via
+ * its own flag — `buildArgs` translates per-agent:
+ *
+ * - Claude: `--effort <level>`, accepts low/medium/high/xhigh/max.
+ * - Codex: `-c model_reasoning_effort=<level>`, accepts minimal/low/medium/high/
+ *   xhigh (no `max` — `buildArgs` clamps `max` → `xhigh`, codex's ceiling).
+ *
+ * Gemini / opencode have no reasoning-effort flag, so they ignore it. Pair a
  * cheap model with low effort for mechanical work and reserve high/max for
  * tasks that genuinely need deeper reasoning.
  */
@@ -41,8 +47,25 @@ export interface AgentSpawnResult {
     readonly attempts: number;
     readonly durationMs: number;
     readonly exitCode: number;
+    /**
+     * True when the spawn failed because the API stayed overloaded (HTTP 529 /
+     * "Overloaded") through every retry. Lets a caller distinguish "back off and
+     * retry later" from "the work genuinely failed" — both surface as a non-zero
+     * `exitCode`, so this is the only way to tell them apart.
+     */
+    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.

package/dist/ai/worktree.js

@@ -133,6 +133,10 @@ async function runOne(item, index, worktreeBranch, worktreePath, baseRepo, branc
 *   ```
 */
 async function spawnAiAgentsInWorktrees(items, fn, options) {
+	options = {
+		__proto__: null,
+		...options
+	};
 	const cleanup = options.cleanup ?? "always";
 	const namePrefix = options.namePrefix ?? "agent-task";
 	const concurrency = require_primordials_math.MathMax(1, Math.min(options.concurrency ?? DEFAULT_CONCURRENCY, MAX_CONCURRENCY));

package/dist/archives/tar.js

@@ -4,8 +4,8 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const require_runtime = require('../_virtual/_rolldown/runtime.js');
 const require_primordials_error = require('../primordials/error.js');
 const require_paths_normalize = require('../paths/normalize.js');
-const require_archives__internal = require('./_internal.js');
 const require_fs_safe = require('../fs/safe.js');
+const require_archives__internal = require('./_internal.js');
 let node_fs = require("node:fs");
 let node_process = require("node:process");
 node_process = require_runtime.__toESM(node_process);

package/dist/archives/zip.js

@@ -2,13 +2,13 @@
 /* Socket Lib - Built with rolldown */
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const require_primordials_error = require('../primordials/error.js');
+const require_primordials_map_set = require('../primordials/map-set.js');
 const require_paths_normalize = require('../paths/normalize.js');
 const require_primordials_array = require('../primordials/array.js');
-const require_primordials_map_set = require('../primordials/map-set.js');
 const require_node_path = require('../node/path.js');
 const require_primordials_promise = require('../primordials/promise.js');
-const require_archives__internal = require('./_internal.js');
 const require_fs_safe = require('../fs/safe.js');
+const require_archives__internal = require('./_internal.js');
 
 //#region src/archives/zip.ts
 /**

package/dist/argv/parse.d.ts

@@ -3,10 +3,28 @@
  *   yargs-parser with a Node.js parseArgs-compatible surface for booleans,
  *   strings, arrays, aliases, defaults, and coercion.
  */
+/**
+ * Yargs parser options interface.
+ */
+export interface YargsOptions {
+    boolean?: string[] | undefined;
+    string?: string[] | undefined;
+    array?: string[] | undefined;
+    alias?: Record<string, string | string[]> | undefined;
+    default?: Record<string, unknown> | undefined;
+    coerce?: Record<string, (value: unknown) => unknown> | undefined;
+    'unknown-options-as-args'?: boolean | undefined;
+    'parse-numbers'?: boolean | undefined;
+    'parse-positional-numbers'?: boolean | undefined;
+    'boolean-negation'?: boolean | undefined;
+    'halt-at-non-option'?: boolean | undefined;
+    configuration?: Record<string, boolean | string> | undefined;
+    strict?: boolean | undefined;
+}
 /**
  * Yargs parser result interface.
  */
-interface YargsArguments extends Record<string, unknown> {
+export interface YargsArguments extends Record<string, unknown> {
     _: string[];
     $0?: string | undefined;
 }
@@ -95,4 +113,3 @@ export declare function parseArgs<T = Record<string, unknown>>(config?: ParseArg
  *   ```
  */
 export declare function parseArgsWithDefaults<T = Record<string, unknown>>(config?: ParseArgsConfig): ParsedArgs<T>;
-export {};

package/dist/argv/parse.js

@@ -2,9 +2,9 @@
 /* Socket Lib - Built with rolldown */
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const require_runtime = require('../_virtual/_rolldown/runtime.js');
+const require_primordials_object = require('../primordials/object.js');
 const require_primordials_string = require('../primordials/string.js');
 const require_primordials_array = require('../primordials/array.js');
-const require_primordials_object = require('../primordials/object.js');
 let node_process = require("node:process");
 node_process = require_runtime.__toESM(node_process);
 let src_external_yargs_parser = require("../external/yargs-parser");

package/dist/arrays/join.js

@@ -77,6 +77,10 @@ function joinAnd(arr) {
 * @returns Formatted string
 */
 function joinList(items, options) {
+	options = {
+		__proto__: null,
+		...options
+	};
 	const w = options?.with;
 	if (w === "and") return require_arrays__internal.getConjunctionFormatter().format(items.map(String));
 	if (w === "or") return require_arrays__internal.getDisjunctionFormatter().format(items.map(String));

package/dist/bin/find.js

@@ -3,18 +3,18 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const require_runtime = require('../_virtual/_rolldown/runtime.js');
 const require_constants_platform = require('../constants/platform.js');
+const require_env_home = require('../env/home.js');
+const require_env_xdg = require('../env/xdg.js');
 const require_primordials_array = require('../primordials/array.js');
 const require_node_fs = require('../node/fs.js');
 const require_node_path = require('../node/path.js');
 const require_bin_which = require('./which.js');
-const require_env_home = require('../env/home.js');
 const require_env_windows = require('../env/windows.js');
-const require_env_xdg = require('../env/xdg.js');
 const require_bin_shadow = require('./shadow.js');
-let src_external_which = require("../external/which");
-src_external_which = require_runtime.__toESM(src_external_which);
 let node_process = require("node:process");
 node_process = require_runtime.__toESM(node_process);
+let src_external_which = require("../external/which");
+src_external_which = require_runtime.__toESM(src_external_which);
 
 //#region src/bin/find.ts
 /**