peaks-loop 4.0.0-beta.8 → 4.0.0-beta.9

package/dist/services/config/config-types.d.ts

@@ -0,0 +1,119 @@
+export type ModelPreference = 'haiku' | 'sonnet' | 'opus' | 'minimax';
+export type ModelProviderId = 'minimax' | string;
+export type ExecutionModelId = string;
+export type ProviderModelConfig = {
+    model?: ExecutionModelId;
+    baseUrl?: string;
+    apiKey?: string;
+};
+export type MiniMaxProviderConfig = ProviderModelConfig;
+export type ModelProviderConfig = {
+    minimax?: MiniMaxProviderConfig;
+    [providerId: string]: ProviderModelConfig | undefined;
+};
+export type ProxyConfig = {
+    httpProxy?: string;
+};
+export type TokenRef = {
+    env: string;
+} | {
+    keychain: string;
+} | {
+    ghCli: true;
+};
+export type TokenConfig = {
+    AnthropicApiKey?: TokenRef;
+    OpenAiApiKey?: TokenRef;
+    GitHubToken?: TokenRef;
+    GitLabToken?: TokenRef;
+};
+export type ArtifactProvider = 'github' | 'gitlab';
+export type ArtifactRemoteRepoConfig = {
+    provider: ArtifactProvider;
+    owner: string;
+    name: string;
+};
+export type ArtifactStorageConfig = {
+    mode: 'local';
+    localPath?: string;
+} | {
+    mode: 'local-with-remote-sync';
+    localPath?: string;
+    remote: ArtifactRemoteRepoConfig;
+};
+export type WorkspaceConfig = {
+    workspaceId: string;
+    name: string;
+    rootPath: string;
+    artifactRepo?: ArtifactRemoteRepoConfig;
+    artifactStorage?: ArtifactStorageConfig;
+    installedCapabilityIds: string[];
+};
+export type OcrAuthHeader = 'authorization' | 'x-api-key' | 'bearer';
+export type OcrLlmConfig = {
+    url?: string;
+    authToken?: string;
+    model?: string;
+    useAnthropic?: boolean;
+    authHeader?: OcrAuthHeader;
+};
+export type OcrConfig = {
+    llm?: OcrLlmConfig;
+};
+/**
+ * 2.0.1 slim `~/.peaks/config.json` schema. The on-disk file holds
+ * ONLY `version` + `ocr.llm.*` placeholders. All other settings
+ * (providers, proxy, workspaces, language/model/economy/swarm
+ * toggles) live in sidecar files under the same `~/.peaks/`
+ * directory or in per-project `preferences.json`.
+ *
+ * The slim shape is enforced on disk by `loadGlobalConfig`; any
+ * unknown field on read is silently stripped and the file is
+ * rewritten with the slim shape, so a hand-written or partially-
+ * migrated file cannot grow stale fields.
+ *
+ * NOTE: legacy fields below are kept on the type as `@deprecated`
+ * so existing consumers (`config-service.ts`, `workflow-commands.ts`,
+ * etc.) continue to compile during the migration window. They are
+ * written to / read from sidecar files at runtime; the slim
+ * `~/.peaks/config.json` only persists `version` + `ocr`.
+ */
+export type PeaksConfig = {
+    version: string;
+    ocr?: OcrConfig;
+    /** @deprecated Moved to `~/.peaks/providers.json` (provider-service.ts) */
+    providers?: ModelProviderConfig;
+    /** @deprecated Moved to `~/.peaks/proxy.json` (proxy-service.ts) */
+    proxy?: ProxyConfig;
+    /** @deprecated Removed in 2.0.1; canonical home is `<project>/.peaks/preferences.json` */
+    language?: string;
+    /** @deprecated Removed in 2.0.1; canonical home is preferences */
+    model?: ModelPreference;
+    /** @deprecated Removed in 2.0.1; canonical home is preferences */
+    economyMode?: boolean;
+    /** @deprecated Removed in 2.0.1; canonical home is preferences */
+    swarmMode?: boolean;
+    /** @deprecated Removed in 2.0.1; never read from this file */
+    tokens?: TokenConfig;
+    /** @deprecated Moved to `~/.peaks/workspaces.json` (workspace-state-service.ts) */
+    workspaces?: WorkspaceConfig[];
+    /** @deprecated Moved to `~/.peaks/workspaces.json` (workspace-state-service.ts) */
+    currentWorkspace?: string | null;
+};
+export type ConfigLayer = 'user' | 'project';
+export type ConfigGetOptions = {
+    key?: string;
+    layer?: ConfigLayer;
+};
+export type ConfigSetOptions = {
+    key: string;
+    value: unknown;
+    layer?: ConfigLayer;
+};
+/**
+ * 2.0.1 slim runtime default for `~/.peaks/config.json`. The on-disk
+ * file only carries `version` + empty `ocr.llm.*` placeholders.
+ */
+export declare const DEFAULT_CONFIG: PeaksConfig;
+export type { ConfigV2 } from './config-migration.js';
+export { isConfigV2 } from './config-migration.js';

package/dist/services/config/config-types.js

@@ -0,0 +1,18 @@
+import { CLI_VERSION } from '../../shared/version.js';
+/**
+ * 2.0.1 slim runtime default for `~/.peaks/config.json`. The on-disk
+ * file only carries `version` + empty `ocr.llm.*` placeholders.
+ */
+export const DEFAULT_CONFIG = {
+    version: CLI_VERSION,
+    ocr: {
+        llm: {
+            url: '',
+            authToken: '',
+            model: '',
+            useAnthropic: false,
+            authHeader: 'authorization'
+        }
+    }
+};
+export { isConfigV2 } from './config-migration.js';

package/dist/services/config/model-routing.d.ts

@@ -0,0 +1,66 @@
+import { type ModelProviderConfig, type PeaksConfig } from './config-types.js';
+/**
+ * Slice 2026-07-09 add-zcode-adapter (A.3): replaces the legacy
+ * `STRONGEST_MODEL_ID = 'claude-opus-4-7'` constant (removed) with a dynamic
+ * resolver. The strongest planner/reviewer model is now derived
+ * from the active config instead of being hardcoded to a specific
+ * vendor. This unlocks running peaks-loop under non-Claude IDEs
+ * (z-code, Cursor, Trae, ...).
+ *
+ * Resolution order:
+ *   1. Explicit `config.model` (user override via `peaks config set model ...`)
+ *   2. Stable fallback for back-compat (env-var override; defaults to
+ *      `claude-opus-4-7` so legacy fixtures keep compiling per
+ *      SC §3.4 strategy A)
+ *
+ * Vendor-neutrality note: the default `'claude-opus-4-7'` is a
+ * *back-compat fallback*, NOT a hardcoded "the strongest model is
+ * always Claude" assumption. Production callers should set
+ * `config.model` (or override the env var) to declare their strongest
+ * model. Adapter-level runtime probing is wired in Slice C
+ * (`getStrongestModelIdAsync` below).
+ */
+export declare function getStrongestModelId(config?: {
+    model?: unknown;
+}): string;
+/**
+ * Slice 2026-07-09 add-zcode-adapter (Slice C, C.4): async variant
+ * of `getStrongestModelId`. Same precedence for layers 1 + 2, but
+ * layer 2.5 is the IDE's runtime probe (`detectCurrentIdeModel`)
+ * which is consulted BEFORE the env-var back-compat fallback.
+ *
+ * Why this exists:
+ *   - `rd-service.buildPlan` (and other sync callers) still call the
+ *     sync `getStrongestModelId` — we do NOT change those signatures.
+ *   - New async callers (the future Slice C-extension of
+ *     `workflow-router-service`, plus any LLM-inside-z-code path)
+ *     resolve the strongest model from the IDE's actual state,
+ *     without forcing the user to set `config.model`.
+ *
+ * Resolution order:
+ *   1. Explicit `config.model`.
+ *   2. `PEAKS_STRONGEST_MODEL_DEFAULT` env var override.
+ *   3. Runtime probe via `detectCurrentIdeModel()` (only when the
+ *      registered IDE adapter opts in via `detectCurrentModel?` —
+ *      only `zcode` does in Slice C; other IDEs skip this layer).
+ *   4. Hardcoded back-compat default `'claude-opus-4-7'`.
+ *
+ * Each layer is isolated so a failure in the probe does not break
+ * the resolver.
+ */
+export declare function getStrongestModelIdAsync(config?: {
+    model?: unknown;
+}, runtimeProbeDisabled?: boolean): Promise<string>;
+export declare function getConfiguredExecutionModelId(providers: ModelProviderConfig | undefined): string;
+/**
+ * Slice 015 — typed exception for "no provider has a configured model".
+ * Lives next to its throw site so a downstream `instanceof` check survives
+ * any tree-shaking. CLI catch sites map this to the `INVALID_PROVIDERS`
+ * envelope code via `_cli-error-envelope.mapServiceError`.
+ */
+export declare class ProviderNotConfiguredError extends Error {
+    constructor(message?: string);
+}
+export declare function getEconomyAwareExecutionModelId(config: Pick<PeaksConfig, 'economyMode' | 'providers'> & {
+    model?: string;
+}): string;

package/dist/services/config/model-routing.js

@@ -0,0 +1,105 @@
+import { detectCurrentIdeModel } from '../ide/current-model-detector.js';
+/**
+ * Slice 2026-07-09 add-zcode-adapter (A.3): replaces the legacy
+ * `STRONGEST_MODEL_ID = 'claude-opus-4-7'` constant (removed) with a dynamic
+ * resolver. The strongest planner/reviewer model is now derived
+ * from the active config instead of being hardcoded to a specific
+ * vendor. This unlocks running peaks-loop under non-Claude IDEs
+ * (z-code, Cursor, Trae, ...).
+ *
+ * Resolution order:
+ *   1. Explicit `config.model` (user override via `peaks config set model ...`)
+ *   2. Stable fallback for back-compat (env-var override; defaults to
+ *      `claude-opus-4-7` so legacy fixtures keep compiling per
+ *      SC §3.4 strategy A)
+ *
+ * Vendor-neutrality note: the default `'claude-opus-4-7'` is a
+ * *back-compat fallback*, NOT a hardcoded "the strongest model is
+ * always Claude" assumption. Production callers should set
+ * `config.model` (or override the env var) to declare their strongest
+ * model. Adapter-level runtime probing is wired in Slice C
+ * (`getStrongestModelIdAsync` below).
+ */
+export function getStrongestModelId(config) {
+    const raw = config?.model;
+    const fromConfig = typeof raw === 'string' ? raw.trim() : undefined;
+    if (fromConfig)
+        return fromConfig;
+    // Slice 2026-07-09: back-compat fallback for test fixtures that
+    // pre-date this slice (SC §3.4 strategy A env-var override).
+    return process.env.PEAKS_STRONGEST_MODEL_DEFAULT ?? 'claude-opus-4-7';
+}
+/**
+ * Slice 2026-07-09 add-zcode-adapter (Slice C, C.4): async variant
+ * of `getStrongestModelId`. Same precedence for layers 1 + 2, but
+ * layer 2.5 is the IDE's runtime probe (`detectCurrentIdeModel`)
+ * which is consulted BEFORE the env-var back-compat fallback.
+ *
+ * Why this exists:
+ *   - `rd-service.buildPlan` (and other sync callers) still call the
+ *     sync `getStrongestModelId` — we do NOT change those signatures.
+ *   - New async callers (the future Slice C-extension of
+ *     `workflow-router-service`, plus any LLM-inside-z-code path)
+ *     resolve the strongest model from the IDE's actual state,
+ *     without forcing the user to set `config.model`.
+ *
+ * Resolution order:
+ *   1. Explicit `config.model`.
+ *   2. `PEAKS_STRONGEST_MODEL_DEFAULT` env var override.
+ *   3. Runtime probe via `detectCurrentIdeModel()` (only when the
+ *      registered IDE adapter opts in via `detectCurrentModel?` —
+ *      only `zcode` does in Slice C; other IDEs skip this layer).
+ *   4. Hardcoded back-compat default `'claude-opus-4-7'`.
+ *
+ * Each layer is isolated so a failure in the probe does not break
+ * the resolver.
+ */
+export async function getStrongestModelIdAsync(config, runtimeProbeDisabled = false) {
+    const raw = config?.model;
+    const fromConfig = typeof raw === 'string' ? raw.trim() : undefined;
+    if (fromConfig)
+        return fromConfig;
+    const envDefault = process.env.PEAKS_STRONGEST_MODEL_DEFAULT;
+    if (envDefault && envDefault.length > 0)
+        return envDefault;
+    if (!runtimeProbeDisabled) {
+        try {
+            const probed = await detectCurrentIdeModel();
+            if (probed && probed.length > 0)
+                return probed;
+        }
+        catch { // TODO(g2): best-effort runtime probe — fall through to back-compat default is intentional
+            // best-effort — fall through to back-compat default
+        }
+    }
+    return 'claude-opus-4-7';
+}
+export function getConfiguredExecutionModelId(providers) {
+    const providerConfigs = Object.values(providers ?? {});
+    const configuredModel = providerConfigs
+        .map((provider) => provider?.model?.trim())
+        .find((model) => typeof model === 'string' && model.length > 0);
+    if (!configuredModel) {
+        throw new ProviderNotConfiguredError();
+    }
+    return configuredModel;
+}
+/**
+ * Slice 015 — typed exception for "no provider has a configured model".
+ * Lives next to its throw site so a downstream `instanceof` check survives
+ * any tree-shaking. CLI catch sites map this to the `INVALID_PROVIDERS`
+ * envelope code via `_cli-error-envelope.mapServiceError`.
+ */
+export class ProviderNotConfiguredError extends Error {
+    constructor(message = 'Execution model must be configured in providers') {
+        super(message);
+        this.name = 'ProviderNotConfiguredError';
+    }
+}
+export function getEconomyAwareExecutionModelId(config) {
+    // Slice 2.0.1-bug1 round 3: economy is the project default. Treat undefined as enabled
+    // (matches the pre-slice implicit default from DEFAULT_CONFIG.economyMode = true). Only an
+    // explicit `economyMode === false` switches execution to the strongest planner/reviewer
+    // model (resolved dynamically per Slice 2026-07-09 add-zcode-adapter A.3).
+    return config.economyMode !== false ? getConfiguredExecutionModelId(config.providers) : getStrongestModelId(config);
+}

package/dist/services/config/provider-service.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Provider configs (MiniMax and other custom providers) live in
+ * `~/.peaks/providers.json` — NOT in the slim `~/.peaks/config.json`.
+ * The slim config only carries `version` + `ocr.llm.*`; provider
+ * model selection, base URLs, and API keys live here in a dedicated
+ * sidecar so the user has one discoverable location for runtime
+ * model-routing settings.
+ *
+ * This module is the only owner of the providers.json file. Reads
+ * from `~/.peaks/config.json.providers` are tolerated as a one-time
+ * back-compat fallback so an unmigrated 1.x-style config still
+ * returns the user's existing MiniMax configuration; the next
+ * `setMiniMaxProviderConfig` call promotes the value into
+ * `~/.peaks/providers.json` and the legacy `~/.peaks/config.json`
+ * field is stripped by `loadGlobalConfig` governance.
+ */
+export declare const MINIMAX_API_HOST = "api.minimaxi.com";
+export type MiniMaxProviderConfig = {
+    model?: string;
+    baseUrl?: string;
+    apiKey?: string;
+};
+export type ProviderModelConfig = MiniMaxProviderConfig;
+export type ModelProviderId = 'minimax' | string;
+export type ExecutionModelId = string;
+export type ModelPreference = 'haiku' | 'sonnet' | 'opus' | 'minimax';
+export type ModelProviderConfig = {
+    minimax?: MiniMaxProviderConfig;
+    [providerId: string]: ProviderModelConfig | undefined;
+};
+export declare function isValidProviderBaseUrl(value: string): boolean;
+export declare function isValidMiniMaxBaseUrl(value: string): boolean;
+export declare function validateMiniMaxBaseUrl(value: unknown): void;
+export declare function validateProviderBaseUrl(value: unknown): void;
+export declare function validateModelProviderConfig(providers: ModelProviderConfig): void;
+export type MiniMaxProviderStatus = {
+    provider: 'minimax';
+    configured: boolean;
+    baseUrlConfigured: boolean;
+    apiKeyConfigured: boolean;
+    storage: 'sidecar-v1';
+    nextActions: string[];
+};
+export declare function getMiniMaxProviderConfig(): MiniMaxProviderConfig;
+export declare function getMiniMaxProviderStatus(): MiniMaxProviderStatus;
+export declare function setMiniMaxProviderConfig(input: MiniMaxProviderConfig): MiniMaxProviderStatus;
+export declare function getAllProviders(): ModelProviderConfig;
+export declare function setProviderConfig(providerId: string, input: ProviderModelConfig): ModelProviderConfig;

package/dist/services/config/provider-service.js

@@ -0,0 +1,143 @@
+import { SIDECAR_SCHEMA_VERSION, ensureSidecarVersion, providersConfigPath, readSidecarJson, writeSidecarJson } from './sidecar-store.js';
+/**
+ * Provider configs (MiniMax and other custom providers) live in
+ * `~/.peaks/providers.json` — NOT in the slim `~/.peaks/config.json`.
+ * The slim config only carries `version` + `ocr.llm.*`; provider
+ * model selection, base URLs, and API keys live here in a dedicated
+ * sidecar so the user has one discoverable location for runtime
+ * model-routing settings.
+ *
+ * This module is the only owner of the providers.json file. Reads
+ * from `~/.peaks/config.json.providers` are tolerated as a one-time
+ * back-compat fallback so an unmigrated 1.x-style config still
+ * returns the user's existing MiniMax configuration; the next
+ * `setMiniMaxProviderConfig` call promotes the value into
+ * `~/.peaks/providers.json` and the legacy `~/.peaks/config.json`
+ * field is stripped by `loadGlobalConfig` governance.
+ */
+export const MINIMAX_API_HOST = 'api.minimaxi.com';
+function loadProvidersSidecar() {
+    const fallback = { version: SIDECAR_SCHEMA_VERSION, providers: {} };
+    const raw = readSidecarJson(providersConfigPath(), fallback);
+    const version = ensureSidecarVersion(raw).version;
+    const providers = sanitizeProviders(raw.providers);
+    return { version, providers };
+}
+function saveProvidersSidecar(providers) {
+    writeSidecarJson(providersConfigPath(), {
+        version: SIDECAR_SCHEMA_VERSION,
+        providers
+    });
+}
+function sanitizeProviders(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return {};
+    const out = {};
+    for (const [id, cfg] of Object.entries(value)) {
+        if (cfg === null || typeof cfg !== 'object' || Array.isArray(cfg))
+            continue;
+        const sanitized = sanitizeMiniMaxLike(cfg);
+        if (Object.keys(sanitized).length > 0) {
+            out[id] = sanitized;
+        }
+    }
+    return out;
+}
+function sanitizeMiniMaxLike(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return {};
+    const v = value;
+    const out = {};
+    if (typeof v.model === 'string' && v.model.trim().length > 0)
+        out.model = v.model.trim();
+    if (typeof v.baseUrl === 'string' && v.baseUrl.length > 0)
+        out.baseUrl = v.baseUrl;
+    if (typeof v.apiKey === 'string' && v.apiKey.length > 0)
+        out.apiKey = v.apiKey;
+    return out;
+}
+export function isValidProviderBaseUrl(value) {
+    try {
+        const url = new URL(value);
+        return url.protocol === 'https:' && url.username.length === 0 && url.password.length === 0 && url.search.length === 0 && url.hash.length === 0;
+    }
+    catch {
+        return false;
+    }
+}
+export function isValidMiniMaxBaseUrl(value) {
+    try {
+        const url = new URL(value);
+        return url.protocol === 'https:' && url.hostname === MINIMAX_API_HOST && url.username.length === 0 && url.password.length === 0 && url.search.length === 0 && url.hash.length === 0;
+    }
+    catch {
+        return false;
+    }
+}
+export function validateMiniMaxBaseUrl(value) {
+    if (value !== undefined && (typeof value !== 'string' || !isValidMiniMaxBaseUrl(value))) {
+        throw new Error('MiniMax base URL must be the MiniMax HTTPS endpoint without embedded credentials');
+    }
+}
+export function validateProviderBaseUrl(value) {
+    if (value !== undefined && (typeof value !== 'string' || !isValidProviderBaseUrl(value))) {
+        throw new Error('Provider base URL must be HTTPS without embedded credentials, query, or fragment');
+    }
+}
+export function validateModelProviderConfig(providers) {
+    validateMiniMaxBaseUrl(providers.minimax?.baseUrl);
+    for (const [providerId, provider] of Object.entries(providers)) {
+        if (providerId !== 'minimax') {
+            validateProviderBaseUrl(provider?.baseUrl);
+        }
+    }
+}
+function createMiniMaxProviderStatus(config) {
+    const baseUrl = config.baseUrl?.trim();
+    const apiKey = config.apiKey?.trim();
+    const baseUrlConfigured = typeof baseUrl === 'string' && baseUrl.length > 0 && isValidMiniMaxBaseUrl(baseUrl);
+    const apiKeyConfigured = typeof apiKey === 'string' && apiKey.length > 0;
+    return {
+        provider: 'minimax',
+        configured: baseUrlConfigured && apiKeyConfigured,
+        baseUrlConfigured,
+        apiKeyConfigured,
+        storage: 'sidecar-v1',
+        nextActions: baseUrlConfigured && apiKeyConfigured ? [] : ['Export MINIMAX_API_KEY and rerun peaks config provider minimax set --base-url <url>']
+    };
+}
+export function getMiniMaxProviderConfig() {
+    return loadProvidersSidecar().providers.minimax ?? {};
+}
+export function getMiniMaxProviderStatus() {
+    return createMiniMaxProviderStatus(getMiniMaxProviderConfig());
+}
+export function setMiniMaxProviderConfig(input) {
+    validateMiniMaxBaseUrl(input.baseUrl);
+    const current = loadProvidersSidecar().providers;
+    const next = {
+        ...current,
+        minimax: {
+            ...current.minimax,
+            ...input
+        }
+    };
+    validateMiniMaxBaseUrl(next.minimax?.baseUrl);
+    saveProvidersSidecar(next);
+    return createMiniMaxProviderStatus(next.minimax ?? {});
+}
+export function getAllProviders() {
+    return loadProvidersSidecar().providers;
+}
+export function setProviderConfig(providerId, input) {
+    if (providerId === 'minimax') {
+        throw new Error('Use setMiniMaxProviderConfig for the minimax provider');
+    }
+    validateProviderBaseUrl(input.baseUrl);
+    const current = loadProvidersSidecar().providers;
+    const sanitized = sanitizeMiniMaxLike(input);
+    const next = { ...current, [providerId]: sanitized };
+    validateProviderBaseUrl(sanitized.baseUrl);
+    saveProvidersSidecar(next);
+    return next;
+}

package/dist/services/config/proxy-service.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Proxy config (`httpProxy`) lives in `~/.peaks/proxy.json` — NOT in
+ * the slim `~/.peaks/config.json`. The slim config only carries
+ * `version` + `ocr.llm.*`; the HTTP/HTTPS proxy the CLI uses for
+ * outbound requests lives here in a dedicated sidecar.
+ *
+ * This module is the only owner of proxy.json. Back-compat reads
+ * from `~/.peaks/config.json.proxy.httpProxy` are tolerated for
+ * legacy configs (1.x); the next `setHttpProxy` call promotes the
+ * value into `~/.peaks/proxy.json` and the legacy config.json field
+ * is stripped by `loadGlobalConfig` governance.
+ */
+export type ProxySidecar = {
+    version: string;
+    httpProxy: string | null;
+};
+export declare function isValidProxyUrl(value: string): boolean;
+export declare function validateProxyUrl(value: unknown): void;
+export declare function getHttpProxy(): string | null;
+export declare function setHttpProxy(httpProxy: string | null): void;
+export declare function clearHttpProxy(): void;

package/dist/services/config/proxy-service.js

@@ -0,0 +1,44 @@
+import { SIDECAR_SCHEMA_VERSION, ensureSidecarVersion, proxyConfigPath, readSidecarJson, writeSidecarJson } from './sidecar-store.js';
+const EMPTY_PROXY = { version: SIDECAR_SCHEMA_VERSION, httpProxy: null };
+export function isValidProxyUrl(value) {
+    try {
+        const url = new URL(value);
+        return (url.protocol === 'http:' || url.protocol === 'https:') && url.username.length === 0 && url.password.length === 0 && url.pathname === '/' && url.search.length === 0 && url.hash.length === 0;
+    }
+    catch {
+        return false;
+    }
+}
+export function validateProxyUrl(value) {
+    if (value === undefined || value === null)
+        return;
+    if (typeof value !== 'string' || !isValidProxyUrl(value)) {
+        throw new Error('Proxy URL must be an HTTP or HTTPS URL without embedded credentials');
+    }
+}
+function loadProxySidecar() {
+    const raw = readSidecarJson(proxyConfigPath(), EMPTY_PROXY);
+    const version = ensureSidecarVersion(raw).version;
+    const httpProxy = typeof raw.httpProxy === 'string' && isValidProxyUrl(raw.httpProxy) ? raw.httpProxy : null;
+    return { version, httpProxy };
+}
+function saveProxySidecar(httpProxy) {
+    writeSidecarJson(proxyConfigPath(), {
+        version: SIDECAR_SCHEMA_VERSION,
+        httpProxy
+    });
+}
+export function getHttpProxy() {
+    return loadProxySidecar().httpProxy;
+}
+export function setHttpProxy(httpProxy) {
+    if (httpProxy === null) {
+        saveProxySidecar(null);
+        return;
+    }
+    validateProxyUrl(httpProxy);
+    saveProxySidecar(httpProxy);
+}
+export function clearHttpProxy() {
+    saveProxySidecar(null);
+}

package/dist/services/config/sidecar-store.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Sidecar storage for `~/.peaks/config.json` (the slim 2.0 file).
+ * The on-disk `~/.peaks/config.json` is strictly `{ version, ocr.llm.* }`.
+ * LIVE runtime data (provider configs, proxy, workspace state) lives in
+ * dedicated sidecar files under the same `~/.peaks/` directory so the
+ * user has one discoverable location for all global peaks state, while
+ * `config.json` itself remains a minimal, schema-validatable artifact.
+ *
+ * Each sidecar has its own `version` field (`"2.0.0"`) for future migrations.
+ * All reads/writes use the same hardened-fs primitives as the main
+ * config file (symlink / hardlink / HTTPS guards via
+ * `validateUserConfigPathForWrite`).
+ */
+export declare const SIDECAR_SCHEMA_VERSION = "2.0.0";
+export declare function providersConfigPath(home?: string): string;
+export declare function proxyConfigPath(home?: string): string;
+export declare function workspacesConfigPath(home?: string): string;
+export declare function sidecarExists(path: string): boolean;
+export declare function readSidecarJson<T>(path: string, fallback: T): T;
+export declare function writeSidecarJson(path: string, content: unknown): void;
+export declare function ensureSidecarVersion(content: {
+    version?: unknown;
+}): {
+    version: string;
+};

package/dist/services/config/sidecar-store.js

@@ -0,0 +1,61 @@
+import { existsSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { readConfigFileSafely, validateUserConfigPathForWrite, writeConfigFileSafely } from './config-safety.js';
+/**
+ * Sidecar storage for `~/.peaks/config.json` (the slim 2.0 file).
+ * The on-disk `~/.peaks/config.json` is strictly `{ version, ocr.llm.* }`.
+ * LIVE runtime data (provider configs, proxy, workspace state) lives in
+ * dedicated sidecar files under the same `~/.peaks/` directory so the
+ * user has one discoverable location for all global peaks state, while
+ * `config.json` itself remains a minimal, schema-validatable artifact.
+ *
+ * Each sidecar has its own `version` field (`"2.0.0"`) for future migrations.
+ * All reads/writes use the same hardened-fs primitives as the main
+ * config file (symlink / hardlink / HTTPS guards via
+ * `validateUserConfigPathForWrite`).
+ */
+export const SIDECAR_SCHEMA_VERSION = '2.0.0';
+const SIDECAR_DIR_NAME = '.peaks';
+const PROVIDERS_FILENAME = 'providers.json';
+const PROXY_FILENAME = 'proxy.json';
+const WORKSPACES_FILENAME = 'workspaces.json';
+const SIDECAR_ERROR_MESSAGE = 'Sidecar config path must stay inside the user root';
+function peaksHomeDir(home) {
+    return join(home ?? homedir(), SIDECAR_DIR_NAME);
+}
+export function providersConfigPath(home) {
+    return join(peaksHomeDir(home), PROVIDERS_FILENAME);
+}
+export function proxyConfigPath(home) {
+    return join(peaksHomeDir(home), PROXY_FILENAME);
+}
+export function workspacesConfigPath(home) {
+    return join(peaksHomeDir(home), WORKSPACES_FILENAME);
+}
+export function sidecarExists(path) {
+    return existsSync(path);
+}
+export function readSidecarJson(path, fallback) {
+    if (!existsSync(path))
+        return fallback;
+    const content = readConfigFileSafely(path, SIDECAR_ERROR_MESSAGE);
+    try {
+        const parsed = JSON.parse(content);
+        if (parsed === null || typeof parsed !== 'object')
+            return fallback;
+        return parsed;
+    }
+    catch {
+        return fallback;
+    }
+}
+export function writeSidecarJson(path, content) {
+    mkdirSync(dirname(path), { recursive: true });
+    const serialized = JSON.stringify(content, null, 2) + '\n';
+    writeConfigFileSafely(path, serialized, () => validateUserConfigPathForWrite(path), SIDECAR_ERROR_MESSAGE);
+}
+export function ensureSidecarVersion(content) {
+    const raw = typeof content.version === 'string' ? content.version : SIDECAR_SCHEMA_VERSION;
+    return { version: raw };
+}