@n1creator/openacp-cli 2026.713.1 → 2026.713.2

package/dist/index.d.ts

@@ -259,6 +259,14 @@ interface InstallContext {
     log: Logger$1;
     /** Root of the OpenACP instance directory (e.g. ~/.openacp) */
     instanceRoot?: string;
+    /** Atomically derive lifecycle settings from a fresh cross-process-locked snapshot. */
+    transactSettings?<T>(prepare: (current: Record<string, unknown>) => {
+        settings: Record<string, unknown>;
+        result: T;
+    } | Promise<{
+        settings: Record<string, unknown>;
+        result: T;
+    }>): Promise<T>;
 }
 /**
  * Context provided to the `migrate()` hook at boot time when the plugin's
@@ -800,6 +808,15 @@ interface ValidationResult {
     valid: boolean;
     errors?: string[];
 }
+/** A settings snapshot and optional in-process side effect committed as one transaction. */
+interface PluginSettingsMutation<T> {
+    settings: Record<string, unknown>;
+    result: T;
+    /** Runs only after the new settings snapshot has been persisted. */
+    apply?: () => void | Promise<void>;
+    /** Restores any partially-applied side effect when apply fails. */
+    rollback?: () => void | Promise<void>;
+}
 /**
  * Manages per-plugin settings files.
  *
@@ -810,20 +827,34 @@ interface ValidationResult {
  */
 declare class SettingsManager {
     private basePath;
+    private static readonly mutationTails;
     constructor(basePath: string);
     /** Returns the base path for all plugin settings directories. */
     getBasePath(): string;
     /** Create a SettingsAPI instance scoped to a specific plugin. */
     createAPI(pluginName: string): SettingsAPI;
-    /** Load a plugin's settings from disk. Returns empty object if file doesn't exist. */
+    /** Load a fresh plugin settings snapshot. Returns empty object if the file doesn't exist. */
     loadSettings(pluginName: string): Promise<Record<string, unknown>>;
     /** Validate settings against a Zod schema. Returns valid if no schema is provided. */
     validateSettings(_pluginName: string, settings: unknown, schema?: ZodSchema): ValidationResult;
     /** Resolve the absolute path to a plugin's settings.json file. */
     getSettingsPath(pluginName: string): string;
     getPluginSettings(pluginName: string): Promise<Record<string, unknown>>;
+    /**
+     * Serialize a read/prepare/persist/apply transaction for one plugin.
+     *
+     * The transaction holds both an in-process queue and a filesystem lock. Its
+     * prepare callback receives a fresh disk snapshot. Persistence uses a content
+     * revision CAS; a pre-commit conflict is retried from a new snapshot, while an
+     * exhausted conflict aborts without applying the runtime side effect. Apply
+     * failures restore the exact previous file content and invoke runtime rollback
+     * before releasing the cross-process lock.
+     */
+    transactPluginSettings<T>(pluginName: string, prepare: (current: Record<string, unknown>) => PluginSettingsMutation<T> | Promise<PluginSettingsMutation<T>>): Promise<T>;
     /** Merge updates into existing settings (shallow merge). */
     updatePluginSettings(pluginName: string, updates: Record<string, unknown>): Promise<void>;
+    private transactOnce;
+    private static serialize;
 }
 
 /** Log rotation and verbosity settings. */
@@ -1577,11 +1608,13 @@ interface ProxyRouteChangeResult {
 
 declare const PROXY_ENV_KEYS: readonly ["HTTP_PROXY", "HTTPS_PROXY", "ALL_PROXY", "NO_PROXY", "http_proxy", "https_proxy", "all_proxy", "no_proxy", "NODE_USE_ENV_PROXY"];
 type RouteTester = (fetcher: typeof fetch) => Promise<void>;
+type ConnectivityPreflight = (fetcher: typeof fetch) => Promise<void>;
 type RouteChangedListener = (scope: string, route: ProxyRoute) => void | Promise<void>;
 /** Scoped network policy. It never mutates process.env or a global fetch dispatcher. */
 declare class ProxyService {
     private readonly retiredLeaseTimeoutMs;
     private readonly allowedNodeEnvironmentFlags;
+    private readonly connectivityPreflight;
     private readonly store;
     private readonly scopes;
     private readonly testers;
@@ -1591,7 +1624,7 @@ declare class ProxyService {
     private mutationQueue;
     private policyGeneration;
     private readonly maxTransports;
-    constructor(instanceRoot: string, retiredLeaseTimeoutMs?: number, allowedNodeEnvironmentFlags?: ReadonlySet<string>);
+    constructor(instanceRoot: string, retiredLeaseTimeoutMs?: number, allowedNodeEnvironmentFlags?: ReadonlySet<string>, connectivityPreflight?: ConnectivityPreflight);
     private serialize;
     getPolicyGeneration(): number;
     private invalidatePolicyBeforeCommit;
@@ -1654,6 +1687,7 @@ declare class ProxyService {
     status(): ProxyStatus;
     private validateRoute;
     private testCandidateRoutes;
+    private candidateTransportIdentity;
     private createProfileFetch;
     /** Direct transport that ignores daemon-wide env proxy flags without global mutation. */
     private createDirectFetch;
@@ -1861,6 +1895,11 @@ type ProviderFactory = (config: SpeechServiceConfig) => {
     stt: Map<string, STTProvider>;
     tts: Map<string, TTSProvider>;
 };
+/** A fully-built provider replacement that can be committed without construction work. */
+interface PreparedProviderRefresh {
+    commit(): void;
+    rollback(): void;
+}
 /**
  * Central service for speech-to-text and text-to-speech operations.
  *
@@ -1877,6 +1916,7 @@ declare class SpeechService {
     private providerFactory?;
     private factoryOwnedSTT;
     private factoryOwnedTTS;
+    private runtimeRevision;
     constructor(config: SpeechServiceConfig);
     /** Set a factory function that can recreate providers from config (for hot-reload) */
     setProviderFactory(factory: ProviderFactory): void;
@@ -1909,6 +1949,14 @@ declare class SpeechService {
     synthesize(text: string, options?: TTSOptions): Promise<TTSResult>;
     /** Replace the active config without rebuilding providers. Use `refreshProviders` to also rebuild. */
     updateConfig(config: SpeechServiceConfig): void;
+    /**
+     * Build and validate a complete factory-owned provider replacement without
+     * changing the active runtime. The returned commit is revision-checked and
+     * preserves providers registered by external plugins. Rollback restores the
+     * exact config, maps, ownership sets, and provider object references captured
+     * immediately before commit.
+     */
+    prepareProviderRefresh(newConfig: SpeechServiceConfig): PreparedProviderRefresh;
     /**
      * Reloads TTS and STT providers from a new config snapshot.
      *
@@ -1919,6 +1967,11 @@ declare class SpeechService {
     refreshProviders(newConfig: SpeechServiceConfig): void;
 }
 
+interface GroqAccessCheck {
+    ok: boolean;
+    status?: number;
+    message: string;
+}
 /**
  * Speech-to-text provider backed by Groq's hosted Whisper API.
  *
@@ -1934,8 +1987,11 @@ declare class GroqSTT implements STTProvider {
     private scopedFetch;
     private getScopedFetch?;
     private endpoint;
+    private accessEndpoint;
     readonly name = "groq";
-    constructor(apiKey: string, defaultModel?: string, scopedFetch?: typeof fetch, getScopedFetch?: (() => typeof fetch) | undefined, endpoint?: string);
+    constructor(apiKey: string, defaultModel?: string, scopedFetch?: typeof fetch, getScopedFetch?: (() => typeof fetch) | undefined, endpoint?: string, accessEndpoint?: string);
+    /** Validate credentials without sending audio or exposing a provider response body. */
+    checkAccess(signal?: AbortSignal): Promise<GroqAccessCheck>;
     /**
      * Transcribes audio using the Groq Whisper API.
      *
@@ -4149,6 +4205,7 @@ interface CreateCodeOpts {
     codeTtlMs?: number;
 }
 
+type TokenStoreWriter = (filePath: string, data: string, encoding: BufferEncoding) => Promise<void>;
 /**
  * Persists JWT tokens and one-time authorization codes to a JSON file.
  *
@@ -4162,19 +4219,31 @@ interface CreateCodeOpts {
  */
 declare class TokenStore {
     private filePath;
+    private readonly writer;
     private tokens;
     private codes;
     private savePromise;
     private savePending;
-    constructor(filePath: string);
+    private saveError;
+    private closePromise;
+    private state;
+    constructor(filePath: string, writer?: TokenStoreWriter);
+    private assertOpen;
     /** Loads token and code state from disk. Safe to call at startup; missing file is not an error. */
     load(): Promise<void>;
+    /** Requests a persistence pass and waits until the coalesced queue is durable. */
     save(): Promise<void>;
+    private writeSnapshot;
     /**
      * Coalesces concurrent writes: if a save is in-flight, sets a pending flag
      * so the next save fires immediately after the current one completes.
      */
     private scheduleSave;
+    /**
+     * Internal queue entry point. It is also used by close() to persist mutations
+     * that were accepted while the store was open, such as a debounced lastUsedAt.
+     */
+    private enqueueSave;
     /** Creates a new token record and schedules a persist. Returns the stored token including its generated id. */
     create(opts: CreateTokenOpts): StoredToken;
     get(id: string): StoredToken | undefined;
@@ -4190,8 +4259,17 @@ declare class TokenStore {
      * so flushing on every call would cause excessive disk I/O.
      */
     updateLastUsed(id: string): void;
-    /** Wait for any in-flight and pending saves to complete */
+    private drainSaveQueue;
+    /** Wait for all accepted mutations to become durable. */
     flush(): Promise<void>;
+    /**
+     * Stops delayed work and drains every save already owned by this store.
+     *
+     * Callers must first stop request producers, then await close() before removing
+     * the store directory. The promise is idempotent so both the HTTP server close
+     * hook and its owning plugin teardown can enforce the same lifecycle boundary.
+     */
+    close(): Promise<void>;
     destroy(): void;
     /** Associate a user ID with a token. Called by identity plugin after /identity/setup. */
     setUserId(tokenId: string, userId: string): void;