@iowarp/clio-coder 0.3.0 → 0.3.2

package/src/domains/prompts/fragments/safety/auto-edit.md

@@ -6,9 +6,9 @@ description: Auto-edit autonomy level
 
 # Auto-edit autonomy
 
-At auto-edit autonomy, workspace edits and dispatches run without asking.
-Recognized commands also run: the builtin no-prompt set (tests, lint, build, git status/diff/log) and commands listed in `.clio-coder/safety.yaml`.
-Any other bash asks for one-shot operator approval instead of running silently. Prefer typed tools (`git`, `verify`) where they exist.
-Commands with pipes, `&&`, or redirects count as unrecognized and ask; `$(...)` and backticks always ask because the safety net cannot scan what they execute.
-system_modify actions ask. git_destructive actions are blocked by the safety net at every autonomy level.
+At auto-edit autonomy, write actions and recognized commands run without asking.
+Recognized commands are the builtin no-prompt set (tests, lint, build, git status/diff/log) and the commands listed in `.clio-coder/safety.yaml`; a `&&` chain whose every step is recognized runs too.
+Any other command is approval-required instead of running silently: pipes, `;`, `||`, redirects, newlines, and a `&&` chain with an unrecognized step all count as unrecognized. Prefer a typed tool over raw shell where one is admitted.
+`$(...)` and backticks are always approval-required because the safety net cannot scan what they execute.
+system_modify actions are approval-required. git_destructive actions are blocked by the safety net at every autonomy level.
 Keep edits focused so each change is easy to review.

package/src/domains/prompts/fragments/safety/full-auto.md

@@ -7,8 +7,8 @@ description: Full-auto autonomy level
 # Full-auto autonomy
 
 At full-auto autonomy, act on the task without asking permission to proceed.
-Writes, dispatches, and bash run without prompting, pipes and `&&` included; the safety net is the protection, not the prompt.
-`$(...)` and backticks still ask for one-shot confirmation because the safety net cannot scan what they execute; prefer typed tools (`git`, `verify`) or split the command.
-system_modify actions still ask: they reach outside the workspace where git cannot undo damage.
+Write actions and commands run without prompting, unrecognized commands with pipes and `&&` included; the safety net is the protection, not the prompt.
+`$(...)` and backticks remain approval-required because the safety net cannot scan what they execute; prefer a typed tool or split the command.
+system_modify actions remain approval-required: they reach outside the workspace where git cannot undo damage.
 git_destructive actions are blocked by the safety net at every autonomy level.
 Confirm outcomes with focused verification instead of broad churn.

package/src/domains/prompts/fragments/safety/read-only.md

@@ -7,7 +7,7 @@ description: Read-only autonomy level
 # Read-only autonomy
 
 At read-only autonomy, inspect and answer; never mutate.
-Read-class tools (read, grep, find, ls, typed git inspection) run freely.
-Every write, command, and dispatch is auto-denied by the harness, and no approval prompt will appear.
-When a change is needed, propose it concretely: the exact file edits or commands the operator should apply.
-The safety net applies at every autonomy level.
+Read-class actions run freely.
+Every mutating call is denied by the harness, and no approval prompt appears.
+When a change is needed, propose it concretely: the exact file edits or commands to apply.
+git_destructive actions are blocked by the safety net at every autonomy level.

package/src/domains/prompts/fragments/safety/suggest.md

@@ -6,8 +6,8 @@ description: Suggest autonomy level
 
 # Suggest autonomy
 
-At suggest autonomy, the operator drives: every non-read action parks for one-shot approval before it runs.
-Read-class tools run freely. Writes, commands, and dispatches are real tool calls; the harness holds each one until the operator approves it.
+At suggest autonomy, every non-read action is approval-required before it runs.
+Read-class actions run freely. Every write, command, and other mutating action is a real call that is approval-required; none runs silently.
 Make each proposed action concrete and minimal so the approval decision is easy.
 Surface assumptions and risks alongside the call, not after it.
 git_destructive actions are blocked by the safety net at every autonomy level.

package/src/domains/prompts/fragments/wiki/page.md

@@ -1,4 +1,14 @@
 ---
+id: wiki.page
+version: 1
+description: >-
+  Wiki page-writing worker prompt, one dispatch per page. context/wiki/prompts.ts
+  substitutes {{pagePath}}, {{pageRelPath}}, and {{pageTitle}} per dispatch. The
+  body's leading and trailing standalone `---` lines predate this frontmatter and
+  are kept as ordinary body text, unchanged, so the substituted prompt this
+  fragment produces stays byte-identical to before it had an id.
+---
+---
 You are writing one page of a repository wiki. One page is your entire job this pass. Another
 writer owns every other page, so do not write, plan, or apologize for any of them.
 

package/src/domains/prompts/fragments/wiki/plan.md

@@ -1,4 +1,14 @@
 ---
+id: wiki.plan
+version: 1
+description: >-
+  Wiki plan-revision worker prompt, one dispatch per generation. context/wiki/prompts.ts
+  substitutes {{planPath}} per dispatch. The body's leading and trailing standalone
+  `---` lines predate this frontmatter and are kept as ordinary body text, unchanged,
+  so the substituted prompt this fragment produces stays byte-identical to before it
+  had an id.
+---
+---
 You are planning a repository wiki. You are not writing it. Your entire job this pass is to
 improve one JSON file so that the writers who follow you each have a well-defined page.
 

package/src/domains/prompts/hash.ts

@@ -0,0 +1,73 @@
+import { createHash } from "node:crypto";
+
+/**
+ * Lowercase-hex SHA-256 of a UTF-8 string.
+ *
+ * Used as the single hash primitive for prompt reproducibility. The prompts
+ * domain wraps this together with `canonicalJson` so that any structural input
+ * (fragment manifests, rendered prompt text) lands on a byte-identical hash
+ * whenever the underlying content is equivalent.
+ */
+export function sha256(input: string): string {
+	return createHash("sha256").update(input, "utf8").digest("hex");
+}
+
+/**
+ * Canonical JSON serialization with stable key order and no whitespace.
+ *
+ * Object keys are sorted recursively; arrays preserve their element order.
+ * Primitives (string, number, boolean, null) serialize via JSON.stringify.
+ * Undefined values in objects are dropped; undefined array entries become null
+ * (matching standard JSON.stringify behavior for arrays). Non-finite numbers
+ * and symbols throw, because they cannot be represented deterministically.
+ */
+export function canonicalJson(value: unknown): string {
+	return serialize(value);
+}
+
+function serialize(value: unknown): string {
+	if (value === null) return "null";
+	if (typeof value === "number") {
+		if (!Number.isFinite(value)) {
+			throw new Error(`canonicalJson: non-finite number ${String(value)} is not representable`);
+		}
+		return JSON.stringify(value);
+	}
+	if (typeof value === "string" || typeof value === "boolean") {
+		return JSON.stringify(value);
+	}
+	if (typeof value === "bigint") {
+		throw new Error("canonicalJson: bigint is not representable");
+	}
+	if (typeof value === "symbol" || typeof value === "function") {
+		throw new Error(`canonicalJson: ${typeof value} is not representable`);
+	}
+	if (value === undefined) {
+		throw new Error("canonicalJson: undefined is not representable at root");
+	}
+	if (Array.isArray(value)) {
+		const parts: string[] = [];
+		for (let i = 0; i < value.length; i++) {
+			// `i in value` distinguishes a real `undefined` from a sparse hole;
+			// both serialize as `null` to match JSON.stringify's array behavior.
+			if (!(i in value) || value[i] === undefined) {
+				parts.push("null");
+				continue;
+			}
+			parts.push(serialize(value[i]));
+		}
+		return `[${parts.join(",")}]`;
+	}
+	if (typeof value === "object") {
+		const obj = value as Record<string, unknown>;
+		const keys = Object.keys(obj).sort();
+		const parts: string[] = [];
+		for (const key of keys) {
+			const child = obj[key];
+			if (child === undefined) continue;
+			parts.push(`${JSON.stringify(key)}:${serialize(child)}`);
+		}
+		return `{${parts.join(",")}}`;
+	}
+	throw new Error(`canonicalJson: unsupported value of type ${typeof value}`);
+}

package/src/domains/prompts/index.ts

@@ -0,0 +1,32 @@
+import type { DomainModule } from "../../core/domain-loader.js";
+import { createPromptsBundle, type PromptsBundleOptions } from "./extension.js";
+import { PromptsManifest } from "./manifest.js";
+
+export const PromptsDomainModule: DomainModule = {
+	manifest: PromptsManifest,
+	createExtension: createPromptsBundle,
+};
+
+/**
+ * Build a `PromptsDomainModule` with bundle options closed over the factory
+ * call. Used by the orchestrator and `clio-coder run` to thread the global
+ * `--no-context-files` startup flag into the prompts domain without
+ * restructuring the domain loader.
+ */
+export function createPromptsDomainModule(options: PromptsBundleOptions = {}): DomainModule {
+	return {
+		manifest:
+			options.noContextFiles === true
+				? {
+						...PromptsManifest,
+						dependsOn: PromptsManifest.dependsOn.filter((name) => name !== "context"),
+					}
+				: PromptsManifest,
+		createExtension: (context) => createPromptsBundle(context, options),
+	};
+}
+
+export type { CompiledSessionPrompt, RenderedPromptFragment, ToolPromptHint, WorkerPromptInputs } from "./compiler.js";
+export type { CompileSessionPromptInput, CompileWorkerPromptInput, PromptsContract } from "./contract.js";
+export type { PromptsBundleOptions } from "./extension.js";
+export { PromptsManifest } from "./manifest.js";

package/src/domains/prompts/manifest.ts

@@ -0,0 +1,8 @@
+import type { DomainManifest } from "../../core/domain-loader.js";
+
+export const PromptsManifest: DomainManifest = {
+	name: "prompts",
+	// agents: the compiled session prompt carries the fleet roster, so the
+	// recipe registry must be loaded before the first compile.
+	dependsOn: ["config", "context", "resources", "agents"],
+};

package/src/domains/prompts/memory-intervention.ts

@@ -0,0 +1,57 @@
+/**
+ * The trajectory this prompt ships with is a JSON list of the action agent's own
+ * tool calls, and a small local model reliably answers in the shape it was just
+ * shown. Measured on the reference route, the earlier wording produced a usable
+ * envelope in 4 of 12 steps; naming the confusion outright took that to 9 of 12,
+ * and adding worked examples took it to 20 of 20 while halving latency, because
+ * the model stops deliberating over what an operation is. The second example
+ * exists because an example that ends in silence anchors silence: with only the
+ * first, the model passed a reminder back on 1 of 4 repeated-failure
+ * trajectories and cited nothing; with both, it spoke on 4 of 4 and cited the
+ * supporting entry every time.
+ */
+export const MEMORY_INTERVENTION_SYSTEM_PROMPT = `You maintain task execution memory for a separate action agent. You never act on the task yourself and you never call tools. You write notes into a memory bank and, rarely, pass one reminder back.
+
+Return exactly two lines and no markdown fences:
+<operations>[JSON operations]</operations>
+<no_intervention/>
+
+Or replace the second line with:
+<context_for_action>one concise reminder</context_for_action>
+
+The operations list holds memory writes only. It is never a list of tool calls, commands, files to read, or next steps. "op" must be exactly one of these four strings and no others:
+- {"op":"update_status","content":"one paragraph"}
+- {"op":"save_knowledge","content":"one stable task fact"}
+- {"op":"save_procedural","content":"one attempt, outcome, diagnosis, or fix"}
+- {"op":"delete","id":"existing entry id"}
+
+Any other "op" value discards that operation. Add "id" to a save only to overwrite an entry already listed in the task bank; omit "id" to record something new. Use at most eight operations, and use <operations>[]</operations> when nothing is worth recording.
+
+Worked example. Given a trajectory where the agent read three routing files and one build command failed twice, a correct response is:
+<operations>[{"op":"update_status","content":"Mapping the routing call chain; the build is still failing."},{"op":"save_knowledge","content":"Target selection runs through placement.ts before runtime-resolution.ts."},{"op":"save_procedural","content":"npm run build failed twice with the same TS2345; the edit did not address it."}]</operations>
+<no_intervention/>
+
+Second worked example. Given a trajectory where the same command failed twice and the bank already holds [tm-p-1] describing that failure, a correct response is:
+<operations>[{"op":"update_status","content":"The same build command has now failed twice with the same error."}]</operations>
+<context_for_action>[tm-p-1] this exact command already failed with this error; change the approach rather than running it again.</context_for_action>
+
+Status is your private progress model and must never appear in context_for_action. Default to <no_intervention/>. Intervene only to restore a relevant bank fact or prevent a repeated known failure. Cite supporting visible entries as [entry-id]. Never restate the latest observation, take over planning, give broad strategy, block a tool, or request continuation.`;
+
+export interface MemoryInterventionPromptInput {
+	task: string;
+	bank: string;
+	trajectory: string;
+}
+
+export function buildMemoryInterventionUserPrompt(input: MemoryInterventionPromptInput): string {
+	return [
+		"Task:",
+		input.task.trim() || "(unknown)",
+		"",
+		"Task bank (status is intentionally omitted):",
+		input.bank.trim() || "(empty)",
+		"",
+		"Recent completed tool trajectory:",
+		input.trajectory.trim() || "[]",
+	].join("\n");
+}

package/src/domains/prompts/preload.ts

@@ -0,0 +1,82 @@
+/**
+ * Project-context preload classification. One place owns the preload cliff:
+ * the session compiler uses it to choose a full effective-handbook preload versus compact
+ * synopsis, and reporting surfaces (context-init output, `clio-coder config
+ * inspect`, the context-window overlay) use it to make the cliff visible.
+ */
+
+export const FULL_PROJECT_CONTEXT_MAX_CHARS = 8000;
+export const FULL_PROJECT_CONTEXT_MAX_LINES = 220;
+
+/** Fraction of a limit at which a full preload is flagged as near the cliff. */
+const NEAR_LIMIT_FRACTION = 0.9;
+
+export type ProjectPreloadMode = "full" | "synopsis" | "none";
+export type ProjectPreloadReason = "size" | "lines" | "no-clio-md";
+
+export interface ProjectPreloadClass {
+	mode: ProjectPreloadMode;
+	/** Rendered project-context length in characters (untrimmed, as measured by the cliff). */
+	chars: number;
+	/** Rendered project-context line count. */
+	lines: number;
+	/** Which limit forced the synopsis; null for full or none. */
+	reason: ProjectPreloadReason | null;
+	/** True when a full preload is within 10% of either limit. */
+	nearLimit: boolean;
+	/** Human line, e.g. "full (5.2kB, 130 lines)" or "synopsis (reason: size)". */
+	label: string;
+}
+
+export interface ClassifyProjectPreloadInput {
+	/** True when at least one selected project handbook contributed to the rendered text. */
+	hasClioMd: boolean;
+	/** The rendered project prompt context (ProjectPromptContext.text). */
+	text: string;
+}
+
+function formatKb(chars: number): string {
+	return `${(chars / 1000).toFixed(1)}kB`;
+}
+
+/**
+ * Classify how the session compiler will treat this project context. Must
+ * mirror the selection in prompts/extension.ts exactly: full preload only
+ * when a selected project handbook parses and the rendered text is within both the
+ * char and line limits; empty text preloads nothing.
+ */
+export function classifyProjectPreload(input: ClassifyProjectPreloadInput): ProjectPreloadClass {
+	const chars = input.text.length;
+	const lines = input.text.length === 0 ? 0 : input.text.split("\n").length;
+	if (input.text.trim().length === 0) {
+		return { mode: "none", chars, lines, reason: null, nearLimit: false, label: "none (no project context)" };
+	}
+	const reason: ProjectPreloadReason | null = !input.hasClioMd
+		? "no-clio-md"
+		: chars > FULL_PROJECT_CONTEXT_MAX_CHARS
+			? "size"
+			: lines > FULL_PROJECT_CONTEXT_MAX_LINES
+				? "lines"
+				: null;
+	if (reason !== null) {
+		return {
+			mode: "synopsis",
+			chars,
+			lines,
+			reason,
+			nearLimit: false,
+			label: `synopsis (reason: ${reason})`,
+		};
+	}
+	const nearLimit =
+		chars > FULL_PROJECT_CONTEXT_MAX_CHARS * NEAR_LIMIT_FRACTION ||
+		lines > FULL_PROJECT_CONTEXT_MAX_LINES * NEAR_LIMIT_FRACTION;
+	return {
+		mode: "full",
+		chars,
+		lines,
+		reason: null,
+		nearLimit,
+		label: `full (${formatKb(chars)}, ${lines} lines)`,
+	};
+}

package/src/domains/providers/auth/api-key.ts

@@ -0,0 +1,47 @@
+import { type ResolveConfigValueOptions, resolveDynamicConfigValue } from "../../../core/resolve-config-value.js";
+import { findEngineEnvKeys, getEngineEnvApiKey } from "../../../engine/env-api-keys.js";
+
+export interface EnvironmentApiKeyResolution {
+	apiKey: string | undefined;
+	source: string | null;
+}
+
+export function resolveStoredApiKey(key: string, providerId = "stored-api-key"): string | undefined {
+	const trimmed = key.trim();
+	if (trimmed.length === 0) return undefined;
+	return resolveProviderDynamicSecret(trimmed, { providerId, field: "apiKey" });
+}
+
+export function normalizeStoredApiKeyRef(key: string): string | undefined {
+	const trimmed = key.trim();
+	return trimmed.length > 0 ? trimmed : undefined;
+}
+
+function resolveProviderDynamicSecret(
+	value: string,
+	context: { providerId: string; targetId?: string; field?: string },
+	options?: ResolveConfigValueOptions,
+): string | undefined {
+	void context;
+	return resolveDynamicConfigValue(value, options);
+}
+
+export function resolveEnvironmentApiKey(providerId: string, explicitEnvVar?: string): EnvironmentApiKeyResolution {
+	if (explicitEnvVar) {
+		const fromExplicit = process.env[explicitEnvVar]?.trim();
+		if (fromExplicit && fromExplicit.length > 0) {
+			return { apiKey: fromExplicit, source: explicitEnvVar };
+		}
+	}
+	for (const envVar of findEngineEnvKeys(providerId) ?? []) {
+		const fromKnownEnv = process.env[envVar]?.trim();
+		if (fromKnownEnv && fromKnownEnv.length > 0) {
+			return { apiKey: fromKnownEnv, source: envVar };
+		}
+	}
+	const fromKnownProvider = getEngineEnvApiKey(providerId)?.trim();
+	if (fromKnownProvider && fromKnownProvider.length > 0) {
+		return { apiKey: fromKnownProvider, source: null };
+	}
+	return { apiKey: undefined, source: explicitEnvVar ?? null };
+}

package/src/domains/providers/auth/backend-file.ts

@@ -0,0 +1,79 @@
+import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { safeResourceWrite } from "../../../core/safe-resource-write.js";
+import { withStateFileLock, withStateFileLockSync } from "../../../core/state-file-lock.js";
+import { clioConfigDir } from "../../../core/xdg.js";
+import type { AuthOperationOptions } from "../../../engine/types.js";
+
+import type { AuthStorageBackend, LockResult } from "./storage.js";
+
+// Both the sync and async lock paths funnel through the canonical writer. It is
+// sync-only, but the credentials file is tiny, the write runs under an exclusive
+// lock on a rare auth path, and delegating additionally gains the directory
+// fsync the hand-rolled variants lacked. The explicit chmod pins the file to
+// exactly 0o600: safeResourceWrite creates its temp with mode 0o600, which umask
+// can still narrow, so we re-assert the secret's mode after the rename.
+function atomicWriteSecret(absPath: string, contents: string): void {
+	safeResourceWrite(absPath, contents, { encoding: "utf8", mode: 0o600 });
+	chmodSync(absPath, 0o600);
+}
+
+export function authStoragePath(): string {
+	return join(clioConfigDir(), "credentials.yaml");
+}
+
+export class FileAuthStorageBackend implements AuthStorageBackend {
+	constructor(private readonly path: string = authStoragePath()) {}
+
+	describe(): string {
+		return this.path;
+	}
+
+	private ensureParentDir(): void {
+		mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 });
+	}
+
+	private ensureFileExists(): void {
+		if (existsSync(this.path)) return;
+		const fd = openSync(this.path, "a", 0o600);
+		closeSync(fd);
+		chmodSync(this.path, 0o600);
+	}
+
+	withLock<T>(fn: (current: string | undefined) => LockResult<T>): T {
+		this.ensureParentDir();
+		this.ensureFileExists();
+		return withStateFileLockSync(this.path, () => {
+			const current = existsSync(this.path) ? readFileSync(this.path, "utf8") : undefined;
+			const { result, next } = fn(current);
+			if (next !== undefined) {
+				atomicWriteSecret(this.path, next);
+			}
+			return result;
+		});
+	}
+
+	async withLockAsync<T>(
+		fn: (current: string | undefined) => Promise<LockResult<T>>,
+		options?: AuthOperationOptions,
+	): Promise<T> {
+		options?.signal?.throwIfAborted();
+		this.ensureParentDir();
+		this.ensureFileExists();
+		return withStateFileLock(
+			this.path,
+			async () => {
+				options?.signal?.throwIfAborted();
+				const current = existsSync(this.path) ? await readFile(this.path, "utf8") : undefined;
+				const { result, next } = await fn(current);
+				options?.signal?.throwIfAborted();
+				if (next !== undefined) {
+					atomicWriteSecret(this.path, next);
+				}
+				return result;
+			},
+			options?.signal ? { signal: options.signal } : {},
+		);
+	}
+}

package/src/domains/providers/auth/backend-memory.ts

@@ -0,0 +1,72 @@
+import type { AuthOperationOptions } from "../../../engine/types.js";
+import type { AuthStorageBackend, LockResult } from "./storage.js";
+
+function abortReason(signal: AbortSignal): unknown {
+	if (signal.reason !== undefined) return signal.reason;
+	const error = new Error("The operation was aborted");
+	error.name = "AbortError";
+	return error;
+}
+
+/** Stop waiting immediately while the queued operation observes its eventual settlement. */
+function raceWithAbortSignal<T>(operation: Promise<T>, signal?: AbortSignal): Promise<T> {
+	if (!signal) return operation;
+	if (signal.aborted) {
+		void operation.catch(() => {});
+		return Promise.reject(abortReason(signal));
+	}
+	return new Promise<T>((resolve, reject) => {
+		let settled = false;
+		const cleanup = (): void => signal.removeEventListener("abort", onAbort);
+		const onAbort = (): void => {
+			if (settled) return;
+			settled = true;
+			cleanup();
+			reject(abortReason(signal));
+		};
+		signal.addEventListener("abort", onAbort, { once: true });
+		void operation.then(
+			(value) => {
+				if (settled) return;
+				settled = true;
+				cleanup();
+				resolve(value);
+			},
+			(error: unknown) => {
+				if (settled) return;
+				settled = true;
+				cleanup();
+				reject(error);
+			},
+		);
+		if (signal.aborted) onAbort();
+	});
+}
+
+export class InMemoryAuthStorageBackend implements AuthStorageBackend {
+	private value: string | undefined;
+	private asyncChain: Promise<unknown> = Promise.resolve();
+
+	withLock<T>(fn: (current: string | undefined) => LockResult<T>): T {
+		const { result, next } = fn(this.value);
+		if (next !== undefined) this.value = next;
+		return result;
+	}
+
+	withLockAsync<T>(
+		fn: (current: string | undefined) => Promise<LockResult<T>>,
+		options?: AuthOperationOptions,
+	): Promise<T> {
+		const previous = this.asyncChain;
+		const operation = (async (): Promise<T> => {
+			await previous.catch(() => {});
+			options?.signal?.throwIfAborted();
+			const { result, next } = await fn(this.value);
+			options?.signal?.throwIfAborted();
+			if (next !== undefined) this.value = next;
+			return result;
+		})();
+		this.asyncChain = operation.catch(() => {});
+		return raceWithAbortSignal(operation, options?.signal);
+	}
+}

package/src/domains/providers/auth/boot-status.ts

@@ -0,0 +1,65 @@
+/** Read-only credential presence check for the pre-TUI target preflight. */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { clioConfigDir } from "../../../core/xdg.js";
+import { findEngineEnvKeys, getEngineEnvApiKey } from "../../../engine/env-api-keys.js";
+import type { TargetDescriptor } from "../types/target-descriptor.js";
+import type { RuntimeAuthMetadata } from "./storage.js";
+
+function record(value: unknown): Record<string, unknown> | null {
+	return value !== null && typeof value === "object" && !Array.isArray(value)
+		? (value as Record<string, unknown>)
+		: null;
+}
+
+function storedCredentialPresent(providerId: string): boolean {
+	const path = join(clioConfigDir(), "credentials.yaml");
+	if (!existsSync(path)) return false;
+	try {
+		const root = record(parseYaml(readFileSync(path, "utf8")));
+		const entry = record(record(root?.entries)?.[providerId]);
+		if (!entry) return false;
+		if (entry.type === "api_key") return typeof entry.key === "string" && entry.key.trim().length > 0;
+		if (entry.type === "oauth") {
+			return typeof entry.access === "string" && typeof entry.refresh === "string" && typeof entry.expires === "number";
+		}
+		// Version 1 (and the historical version-less form).
+		return typeof entry.key === "string" && entry.key.trim().length > 0;
+	} catch {
+		return false;
+	}
+}
+
+function environmentCredentialPresent(providerId: string, explicitEnvVar?: string): boolean {
+	if (explicitEnvVar && process.env[explicitEnvVar]?.trim()) return true;
+	for (const name of findEngineEnvKeys(providerId) ?? []) {
+		if (process.env[name]?.trim()) return true;
+	}
+	return Boolean(getEngineEnvApiKey(providerId)?.trim());
+}
+
+export interface BootAuthStatus {
+	providerId: string;
+	required: boolean;
+	available: boolean;
+}
+
+export function bootAuthStatus(target: TargetDescriptor, runtime: RuntimeAuthMetadata): BootAuthStatus {
+	const required =
+		runtime.auth === "oauth" ||
+		(runtime.auth === "api-key" &&
+			(Boolean(target.auth?.apiKeyEnvVar || target.auth?.apiKeyRef || target.auth?.oauthProfile) ||
+				runtime.tier === "cloud" ||
+				Boolean(runtime.credentialsEnvVar)));
+	const providerId =
+		target.auth?.oauthProfile?.trim() || target.auth?.apiKeyRef?.trim() || runtime.oauthProviderId || runtime.id;
+	if (!required) return { providerId, required: false, available: true };
+	const explicitEnvVar = target.auth?.apiKeyEnvVar ?? runtime.credentialsEnvVar;
+	return {
+		providerId,
+		required: true,
+		available: storedCredentialPresent(providerId) || environmentCredentialPresent(providerId, explicitEnvVar),
+	};
+}

package/src/domains/providers/auth/index.ts

@@ -0,0 +1,37 @@
+import { FileAuthStorageBackend } from "./backend-file.js";
+import { InMemoryAuthStorageBackend } from "./backend-memory.js";
+import { AuthStorage, type AuthStorageData } from "./storage.js";
+
+export function openAuthStorage(path?: string): AuthStorage {
+	return new AuthStorage(new FileAuthStorageBackend(path));
+}
+
+export function createMemoryAuthStorage(data: AuthStorageData = {}): AuthStorage {
+	const backend = new InMemoryAuthStorageBackend();
+	const storage = new AuthStorage(backend);
+	for (const [providerId, credential] of Object.entries(data)) {
+		storage.set(providerId, credential);
+	}
+	return storage;
+}
+
+export { authStoragePath, FileAuthStorageBackend } from "./backend-file.js";
+export { InMemoryAuthStorageBackend } from "./backend-memory.js";
+export type {
+	ApiKeyCredential,
+	AuthCredential,
+	AuthResolution,
+	AuthStatus,
+	AuthStorageBackend,
+	AuthStorageData,
+	AuthTarget,
+	OAuthCredential,
+} from "./storage.js";
+export {
+	AuthStorage,
+	AuthStorageDamagedError,
+	authNotRequiredStatus,
+	resolveAuthTarget,
+	resolveRuntimeAuthTarget,
+	targetRequiresAuth,
+} from "./storage.js";