@n1creator/openacp-cli 2026.712.7 → 2026.712.9

package/dist/index.d.ts

@@ -1260,7 +1260,7 @@ declare class AgentInstance extends TypedEmitter<AgentInstanceEvents> {
      *
      * Does NOT create a session — callers must follow up with newSession or loadSession.
      */
-    static spawnSubprocess(agentDef: AgentDefinition, workingDirectory: string, allowedPaths?: string[]): Promise<AgentInstance>;
+    static spawnSubprocess(agentDef: AgentDefinition, workingDirectory: string, allowedPaths?: string[], environment?: Record<string, string>): Promise<AgentInstance>;
     /**
      * Monitor the subprocess for unexpected exits and emit error events.
      *
@@ -1309,7 +1309,7 @@ declare class AgentInstance extends TypedEmitter<AgentInstanceEvents> {
      * @param mcpServers - Optional MCP server configs to extend agent capabilities
      * @param allowedPaths - Extra filesystem paths the agent may access
      */
-    static spawn(agentDef: AgentDefinition, workingDirectory: string, mcpServers?: McpServerConfig[], allowedPaths?: string[]): Promise<AgentInstance>;
+    static spawn(agentDef: AgentDefinition, workingDirectory: string, mcpServers?: McpServerConfig[], allowedPaths?: string[], environment?: Record<string, string>): Promise<AgentInstance>;
     /**
      * Spawn a new subprocess and restore an existing agent session.
      *
@@ -1319,7 +1319,7 @@ declare class AgentInstance extends TypedEmitter<AgentInstanceEvents> {
      *
      * @param agentSessionId - The agent-side session ID to restore
      */
-    static resume(agentDef: AgentDefinition, workingDirectory: string, agentSessionId: string, mcpServers?: McpServerConfig[], allowedPaths?: string[]): Promise<AgentInstance>;
+    static resume(agentDef: AgentDefinition, workingDirectory: string, agentSessionId: string, mcpServers?: McpServerConfig[], allowedPaths?: string[], environment?: Record<string, string>): Promise<AgentInstance>;
     /**
      * Build the ACP Client callback object.
      *
@@ -1418,13 +1418,15 @@ declare class AgentStore {
  * and resolution (name → AgentDefinition for spawning).
  */
 declare class AgentCatalog {
+    private scopedFetch;
+    private registryUrl;
     private store;
     /** Agents available in the remote registry (cached in memory after load). */
     private registryAgents;
     private cachePath;
     /** Directory where binary agent archives are extracted to. */
     private agentsDir;
-    constructor(store: AgentStore, cachePath: string, agentsDir?: string);
+    constructor(store: AgentStore, cachePath: string, agentsDir?: string, scopedFetch?: typeof fetch, registryUrl?: string);
     /**
      * Load installed agents from disk and hydrate the registry from cache/snapshot.
      *
@@ -1485,6 +1487,144 @@ declare class AgentCatalog {
     private loadRegistryFromCacheOrSnapshot;
 }
 
+declare const PROXY_PROTOCOLS: readonly ["http", "https", "socks5", "socks5h"];
+type ProxyProtocol = typeof PROXY_PROTOCOLS[number];
+type ProxyRoute = 'direct' | 'inherit' | `profile:${string}`;
+interface ProxyProfileInput {
+    id: string;
+    name?: string;
+    protocol: ProxyProtocol;
+    host: string;
+    port: number;
+    username?: string;
+    password?: string;
+    noProxy?: string[];
+    failClosed?: boolean;
+}
+/** Persisted and API-safe profile. Credentials are deliberately absent. */
+interface ProxyProfile {
+    id: string;
+    name: string;
+    protocol: ProxyProtocol;
+    host: string;
+    port: number;
+    noProxy: string[];
+    failClosed: boolean;
+    hasCredentials: boolean;
+}
+interface ProxyRoutingConfig {
+    global: ProxyRoute;
+    routes: Record<string, ProxyRoute>;
+}
+interface ProxyStatus {
+    revision: number;
+    profiles: ProxyProfile[];
+    routing: ProxyRoutingConfig;
+    scopes: string[];
+    diagnostics: Array<{
+        scope: string;
+        route: ProxyRoute;
+        resolvedFrom: string;
+        childProcessSupport: 'native-env' | 'best-effort-socks-env' | 'not-applicable';
+        warning?: string;
+    }>;
+    environment: {
+        daemonWideProxyActive: boolean;
+        compatibilityMode: boolean;
+        variables: string[];
+        message: string;
+    };
+}
+interface ProxyRouteResolution {
+    scope: string;
+    route: ProxyRoute;
+    resolvedFrom: string;
+    profile?: ProxyProfile;
+}
+interface ProxyRouteChangeResult {
+    scope: string;
+    route: ProxyRoute;
+    warmPoolInvalidated: boolean;
+    activeAgentProcessesUnaffected: boolean;
+}
+
+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 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 store;
+    private readonly scopes;
+    private readonly testers;
+    private readonly listeners;
+    private readonly transports;
+    private readonly facades;
+    private mutationQueue;
+    private policyGeneration;
+    private readonly maxTransports;
+    constructor(instanceRoot: string, retiredLeaseTimeoutMs?: number, allowedNodeEnvironmentFlags?: ReadonlySet<string>);
+    private serialize;
+    getPolicyGeneration(): number;
+    private invalidatePolicyBeforeCommit;
+    registerScope(scope: string): () => void;
+    registerRouteTester(scope: string, tester: RouteTester): () => void;
+    /**
+     * Scope discovery is part of the durable policy schema, not only an in-memory
+     * UI concern. Persisting registrations lets an operator configure a plugin or
+     * agent while it is temporarily disabled and keeps the category list stable
+     * across daemon restarts.
+     */
+    private persistScope;
+    onRouteChanged(listener: RouteChangedListener): () => void;
+    listProfiles(): ProxyProfile[];
+    getProfile(id: string): ProxyProfile | undefined;
+    saveProfile(input: ProxyProfileInput): ProxyProfile;
+    private buildProfile;
+    saveProfileSafely(input: ProxyProfileInput, expectedRevision?: number): Promise<ProxyProfile>;
+    /** Import a conventional proxy env file without ever returning or logging its credential URL. */
+    importEnvFile(id: string, envFile: string, name?: string): ProxyProfile;
+    private parseEnvFile;
+    importEnvFileSafely(id: string, envFile: string, name?: string, expectedRevision?: number): Promise<ProxyProfile>;
+    deleteProfile(id: string, expectedRevision?: number): Promise<void>;
+    resolve(scope: string, routeOverride?: ProxyRoute): ProxyRouteResolution;
+    private resolveFromConfig;
+    setRoute(scope: string, route: ProxyRoute, expectedRevision?: number): Promise<ProxyRouteChangeResult>;
+    clearRoute(scope: string, expectedRevision?: number): Promise<void>;
+    getKnownScopes(): string[];
+    createFetch(scope: string, routeOverride?: ProxyRoute): typeof fetch;
+    private createTransport;
+    private cacheTransport;
+    buildAgentEnv(agentName: string, inherited: Record<string, string>): Record<string, string>;
+    buildChildEnv(scope: string, inherited: Record<string, string>): Record<string, string>;
+    test(scope: string, targetUrl?: string): Promise<{
+        ok: boolean;
+        status?: number;
+        error?: string;
+    }>;
+    testProfile(id: string, targetUrl?: string): Promise<{
+        ok: boolean;
+        status?: number;
+        error?: string;
+    }>;
+    status(): ProxyStatus;
+    private validateRoute;
+    private testCandidateRoutes;
+    private createProfileFetch;
+    /** Direct transport that ignores daemon-wide env proxy flags without global mutation. */
+    private createDirectFetch;
+    private acquireTransport;
+    private releaseTransport;
+    private retireTransport;
+    private destroyTransport;
+    private retireScopes;
+    private scopesUsingProfile;
+    private changedResolutionScopes;
+    private allScopes;
+    private releaseWithResponse;
+}
+
 /**
  * High-level facade for spawning and resuming agent instances.
  *
@@ -1502,10 +1642,13 @@ declare class AgentCatalog {
  */
 declare class AgentManager {
     private catalog;
+    private proxyService?;
     private warmEntry;
     /** In-flight prewarm promise — guards against concurrent prewarm calls. */
     private warming;
-    constructor(catalog: AgentCatalog);
+    constructor(catalog: AgentCatalog, proxyService?: ProxyService | undefined);
+    private currentPolicyGeneration;
+    private childEnv;
     /** Return definitions for all installed agents. */
     getAvailableAgents(): AgentDefinition[];
     /** Look up a single agent definition by its short name (e.g., "claude", "gemini"). */
@@ -1743,8 +1886,10 @@ declare class SpeechService {
 declare class GroqSTT implements STTProvider {
     private apiKey;
     private defaultModel;
+    private scopedFetch;
+    private getScopedFetch?;
     readonly name = "groq";
-    constructor(apiKey: string, defaultModel?: string);
+    constructor(apiKey: string, defaultModel?: string, scopedFetch?: typeof fetch, getScopedFetch?: (() => typeof fetch) | undefined);
     /**
      * Transcribes audio using the Groq Whisper API.
      *
@@ -3342,6 +3487,8 @@ declare class OpenACPCore {
     readonly menuRegistry: MenuRegistry;
     readonly assistantRegistry: AssistantRegistry;
     assistantManager: AssistantManager;
+    /** Scoped proxy policy shared by transports, agent spawns, API and commands. */
+    readonly proxyService: ProxyService;
     /** @throws if the service hasn't been registered by its plugin yet */
     private getService;
     /** Access control and rate-limiting guard (provided by security plugin). */
@@ -3673,9 +3820,11 @@ interface PendingFix {
 declare class DoctorEngine {
     private dryRun;
     private dataDir;
+    private proxyService;
     constructor(options?: {
         dryRun?: boolean;
         dataDir?: string;
+        proxyService?: Pick<ProxyService, "createFetch">;
     });
     /**
      * Executes all checks and returns an aggregated report.
@@ -5035,6 +5184,8 @@ declare class TelegramAdapter extends MessagingAdapter {
     private _prerequisiteWatcher;
     /** Set during normal shutdown so bot.stop() does not trigger a self-restart. */
     private _stopping;
+    private unregisterProxyTester?;
+    private telegramFetch;
     /** Returns the configured Telegram supergroup chat ID. */
     getChatId(): number;
     /**
@@ -5201,4 +5352,4 @@ declare class TelegramAdapter extends MessagingAdapter {
     archiveSessionTopic(sessionId: string): Promise<void>;
 }
 
-export { ActivityTracker, AdapterCapabilities, AgentCapabilities, AgentCatalog, AgentCommand, AgentDefinition, AgentEvent, AgentInstance, AgentListItem, AgentManager, AgentStore, AgentSwitchEntry, type ApiConfig, type ApiServerInstance, type ApiServerOptions, type ApiServerService, type AssistantCommand, AssistantManager, AssistantRegistry, type AssistantSection, Attachment, AvailabilityResult, BaseRenderer, type BridgeDeps, CONFIG_REGISTRY, ChannelConfig, type CleanupResult, type CommandArgs, type CommandDef, CommandRegistry, type CommandResponse, type Config, type ConfigFieldDef, ConfigManager, ConfigOption, ContextManager, type ContextOptions, type ContextProvider, type ContextQuery, type ContextResult, type ContextService, type SessionInfo as ContextSessionInfo, type DeleteTopicResult, DisplaySpecBuilder, DisplayVerbosity, DoctorEngine, type DoctorReport, DraftManager, EntireProvider, EventBus, type EventBusEvents, type FieldDef, FileService, type FileServiceInterface, GroqSTT, IChannelAdapter, type IRenderer, IncomingMessage, type InstallContext, InstallProgress, InstallResult, InstalledAgent, type ListItem, type Logger, type LoggingConfig, McpServerConfig, type MenuItem, type MenuOption, MenuRegistry, MessageTransformer, MessagingAdapter, type MessagingAdapterConfig, type MiddlewareHook, type MiddlewarePayloadMap, type MigrateContext, NotificationService as NotificationManager, NotificationMessage, type NotificationService$1 as NotificationService, OpenACPCore, type OpenACPPlugin, OutgoingMessage, OutputMode, OutputModeResolver, PRODUCT_GUIDE, type PendingFix, PermissionGate, PermissionRequest, PlanEntry, type PluginContext, type PluginPermission, type PluginStorage, PromptQueue, RegistryAgent, type RenderedMessage, SSEManager, type STTOptions, type STTProvider, type STTResult, SecurityGuard, type SecurityService, SendQueue, Session, SessionBridge, type SessionCreateParams, type SessionEvents, SessionFactory, type SessionListResult, SessionManager, SessionRecord, SessionStatus, type SessionSummary, SetConfigOptionValue, type SettingsAPI, type SideEffectDeps, type SpeechProviderConfig, SpeechService, type SpeechServiceConfig, type SpeechServiceInterface, StaticServer, StderrCapture, StopReason, StreamAdapter, type TTSOptions, type TTSProvider, type TTSResult, TelegramAdapter, type TerminalIO, ThoughtBuffer, type ThoughtDisplaySpec, ToolCallMeta, ToolCallTracker, type ToolCardSnapshot, ToolCardState, type ToolCardStateConfig, type ToolDisplaySpec, type ToolEntry, ToolStateMap, type TopicInfo, TopicManager, type TunnelServiceInterface, TurnContext, TurnMeta, TurnRouting, TypedEmitter, UsageRecord, UsageRecordEvent, type UsageService, ViewerLinks, cleanupOldSessionLogs, createApiServer, createApiServerService, createChildLogger, createSessionLogger, expandHome, extractContentText, formatTokens, formatToolSummary, formatToolTitle, getConfigValue, getFieldDef, getPidPath, getSafeFields, getStatus, initLogger, installAutoStart, isAutoStartInstalled, isAutoStartSupported, isHotReloadable, log, nodeToWebReadable, nodeToWebWritable, progressBar, resolveOptions, resolveToolIcon, runConfigEditor, setLogLevel, shutdownLogger, splitMessage, startDaemon, stopDaemon, stripCodeFences, truncateContent, uninstallAutoStart };
+export { ActivityTracker, AdapterCapabilities, AgentCapabilities, AgentCatalog, AgentCommand, AgentDefinition, AgentEvent, AgentInstance, AgentListItem, AgentManager, AgentStore, AgentSwitchEntry, type ApiConfig, type ApiServerInstance, type ApiServerOptions, type ApiServerService, type AssistantCommand, AssistantManager, AssistantRegistry, type AssistantSection, Attachment, AvailabilityResult, BaseRenderer, type BridgeDeps, CONFIG_REGISTRY, ChannelConfig, type CleanupResult, type CommandArgs, type CommandDef, CommandRegistry, type CommandResponse, type Config, type ConfigFieldDef, ConfigManager, ConfigOption, ContextManager, type ContextOptions, type ContextProvider, type ContextQuery, type ContextResult, type ContextService, type SessionInfo as ContextSessionInfo, type DeleteTopicResult, DisplaySpecBuilder, DisplayVerbosity, DoctorEngine, type DoctorReport, DraftManager, EntireProvider, EventBus, type EventBusEvents, type FieldDef, FileService, type FileServiceInterface, GroqSTT, IChannelAdapter, type IRenderer, IncomingMessage, type InstallContext, InstallProgress, InstallResult, InstalledAgent, type ListItem, type Logger, type LoggingConfig, McpServerConfig, type MenuItem, type MenuOption, MenuRegistry, MessageTransformer, MessagingAdapter, type MessagingAdapterConfig, type MiddlewareHook, type MiddlewarePayloadMap, type MigrateContext, NotificationService as NotificationManager, NotificationMessage, type NotificationService$1 as NotificationService, OpenACPCore, type OpenACPPlugin, OutgoingMessage, OutputMode, OutputModeResolver, PRODUCT_GUIDE, PROXY_ENV_KEYS, type PendingFix, PermissionGate, PermissionRequest, PlanEntry, type PluginContext, type PluginPermission, type PluginStorage, PromptQueue, type ProxyProfile, type ProxyProfileInput, type ProxyProtocol, type ProxyRoute, type ProxyRouteChangeResult, type ProxyRouteResolution, type ProxyRoutingConfig, ProxyService, type ProxyStatus, RegistryAgent, type RenderedMessage, SSEManager, type STTOptions, type STTProvider, type STTResult, SecurityGuard, type SecurityService, SendQueue, Session, SessionBridge, type SessionCreateParams, type SessionEvents, SessionFactory, type SessionListResult, SessionManager, SessionRecord, SessionStatus, type SessionSummary, SetConfigOptionValue, type SettingsAPI, type SideEffectDeps, type SpeechProviderConfig, SpeechService, type SpeechServiceConfig, type SpeechServiceInterface, StaticServer, StderrCapture, StopReason, StreamAdapter, type TTSOptions, type TTSProvider, type TTSResult, TelegramAdapter, type TerminalIO, ThoughtBuffer, type ThoughtDisplaySpec, ToolCallMeta, ToolCallTracker, type ToolCardSnapshot, ToolCardState, type ToolCardStateConfig, type ToolDisplaySpec, type ToolEntry, ToolStateMap, type TopicInfo, TopicManager, type TunnelServiceInterface, TurnContext, TurnMeta, TurnRouting, TypedEmitter, UsageRecord, UsageRecordEvent, type UsageService, ViewerLinks, cleanupOldSessionLogs, createApiServer, createApiServerService, createChildLogger, createSessionLogger, expandHome, extractContentText, formatTokens, formatToolSummary, formatToolTitle, getConfigValue, getFieldDef, getPidPath, getSafeFields, getStatus, initLogger, installAutoStart, isAutoStartInstalled, isAutoStartSupported, isHotReloadable, log, nodeToWebReadable, nodeToWebWritable, progressBar, resolveOptions, resolveToolIcon, runConfigEditor, setLogLevel, shutdownLogger, splitMessage, startDaemon, stopDaemon, stripCodeFences, truncateContent, uninstallAutoStart };