@spotpatch/dev-server 0.7.0 → 0.9.0

package/dist/index.d.cts

@@ -1,8 +1,18 @@
-import { applyPreparedAgentChange, executeAgentChange, inspectAgentWorkspace, probeProviderCapability, resolveProviderCredential, revertPreparedAgentChange } from '@spotpatch/agent';
-import { AgentJobEvent, AgentJobSnapshot, AgentJobCreateRequest, AgentCapabilityRequest, AgentCapabilitySnapshot, AgentJobResultResponse, AgentWorkspaceHealthSnapshot, ResolvedAiOptions, ExternalHandoffFramework, ExternalHandoffCapability, ExternalHandoffPublishRequest, SpotAnnotation, ExternalHandoffPublishResult, ExternalHandoffStatusResult, ExternalAgentControlStatus, ExternalAgentControlConnectRequest, ExternalAgentControlDisconnectRequest, ExternalAgentControlCancelRequest, ExternalAgentManagedResult, SpotPatchEditorPreference, ContextBudget, SpotPatchLocalePreference, DataFlowLimits, AiProviderProtocol, AiProviderAuthentication, AiExecutionOptions, AiOptions, RuntimeAiConfig, RuntimeDataFlowConfig, ResolvedAgentCheckDefinition, AgentLimits, SpotPatchRuntimeConfig } from '@spotpatch/shared';
+import { applyPreparedAgentChange, executeAgentChange, inspectAgentWorkspace, probeProviderCapability, resolveProviderCredential, revertPreparedAgentChange, AskSourceGrant, ContextualAskReadSnapshot, AskSourceGrantEntry, ContextualAskExecutor } from '@spotpatch/agent';
+import { AgentJobEvent, AgentJobSnapshot, AgentJobCreateRequest, AgentCapabilityRequest, AgentCapabilitySnapshot, AgentJobResultResponse, AgentWorkspaceHealthSnapshot, ResolvedAiOptions, ExternalHandoffFramework, ExternalHandoffCapability, ExternalHandoffPublishRequest, SpotAnnotation, ExternalHandoffPublishResult, ExternalHandoffStatusResult, ExternalAgentControlStatus, ExternalAgentControlConnectRequest, ExternalAgentControlDisconnectRequest, ExternalAgentControlCancelRequest, ExternalAgentManagedResult, SpotPatchEditorPreference, ContextBudget, SpotPatchLocalePreference, DataFlowLimits, ContextualAskExecutorPreference, AiProviderProtocol, AiProviderAuthentication, AiExecutionOptions, AiOptions, ContextualAskOptions, RuntimeAiConfig, RuntimeDataFlowConfig, ResolvedAgentCheckDefinition, AgentLimits, SpotSelectionContext, AskJobEvent, AskJobSnapshot, ContextualAskCapability, AskJobCreateRequest, AskJobResultResponse, ContextualAskErrorCode, SpotPatchRuntimeConfig } from '@spotpatch/shared';
 import { SourceFilterEntry } from '@spotpatch/compiler';
 import { IncomingMessage, ServerResponse } from 'node:http';
 
+type WorkspaceActivityKind = "ask" | "change";
+interface WorkspaceActivityLease {
+    release(): void;
+}
+interface WorkspaceActivityCoordinator {
+    acquire(kind: WorkspaceActivityKind): WorkspaceActivityLease | undefined;
+    current(): WorkspaceActivityKind | undefined;
+}
+declare function createWorkspaceActivityCoordinator(): WorkspaceActivityCoordinator;
+
 type AgentJobEventListener = (event: AgentJobEvent) => void;
 interface AgentJobManager {
     apply(jobId: string): Promise<AgentJobSnapshot>;
@@ -32,6 +42,7 @@ interface CreateAgentJobManagerOptions {
     readonly environment?: Readonly<Record<string, string | undefined>>;
     readonly fetch?: typeof globalThis.fetch;
     readonly root: string;
+    readonly coordinator?: WorkspaceActivityCoordinator;
 }
 declare function createAgentJobManager(options: CreateAgentJobManagerOptions): AgentJobManager;
 
@@ -93,6 +104,11 @@ interface SpotPatchOptions {
     readonly ai?: SpotPatchAiOptions;
     readonly dataFlow?: false | SpotPatchDataFlowOptions;
     readonly externalAgent?: boolean;
+    readonly contextualAsk?: ContextualAskOptions;
+}
+interface ResolvedContextualAskOptions {
+    readonly enabled: boolean;
+    readonly defaultExecutor?: ContextualAskExecutorPreference;
 }
 interface ResolvedSpotPatchOptions {
     readonly enabled: boolean;
@@ -111,6 +127,7 @@ interface ResolvedSpotPatchOptions {
     readonly externalAgent: Readonly<{
         enabled: boolean;
     }>;
+    readonly contextualAsk: ResolvedContextualAskOptions;
 }
 interface ResolvedSpotPatchDataFlowOptions {
     readonly enabled: boolean;
@@ -155,11 +172,15 @@ declare const DEFAULT_OPTIONS: Readonly<{
             readonly graphMaxCallsites: 100;
             readonly analysisTimeoutMs: 2000;
             readonly reportMaxFields: 100;
+            readonly sourceMaxComponents: 256;
         }>;
     }>;
     externalAgent: Readonly<{
         enabled: false;
     }>;
+    contextualAsk: Readonly<{
+        enabled: false;
+    }>;
 }>;
 declare function createRuntimeAiConfig(options: false | ResolvedAiOptions): RuntimeAiConfig;
 declare function createRuntimeDataFlowConfig(options: ResolvedSpotPatchDataFlowOptions): RuntimeDataFlowConfig;
@@ -216,8 +237,9 @@ type SourceIdFactory = () => string;
 
 interface SourceRegistry {
     register(absolutePath: string): string;
-    registerDataFlowComponents(absolutePath: string, sourceVersion: string, components: readonly DataFlowComponentAnchorInput[]): void;
+    registerDataFlowComponents(absolutePath: string, sourceVersion: string, components: readonly DataFlowComponentAnchorInput[]): string;
     resolve(fileId: string): string | undefined;
+    findRegisteredId(absolutePath: string): string | undefined;
     resolveDataFlowComponent(componentSourceId: string): DataFlowComponentAnchor | undefined;
     clear(): void;
 }
@@ -235,6 +257,75 @@ interface SourceRegistryOptions {
 }
 declare function createSourceRegistry(options?: SourceRegistryOptions): SourceRegistry;
 
+interface CapturedAskReadSnapshot {
+    readonly grant: AskSourceGrant;
+    readonly snapshot: ContextualAskReadSnapshot;
+    dispose(): void;
+    isStale(): Promise<boolean>;
+    projectCitation(handleId: string, startLine: number, endLine: number): AskSourceGrantEntry & Readonly<{
+        startLine: number;
+        endLine: number;
+    }>;
+}
+interface CaptureAskReadSnapshotOptions {
+    readonly root: string;
+    readonly registry: SourceRegistry;
+    readonly selection: SpotSelectionContext;
+    readonly signal?: AbortSignal;
+    readonly createHandleId?: () => string;
+}
+declare function captureAskReadSnapshot(options: CaptureAskReadSnapshotOptions): Promise<CapturedAskReadSnapshot>;
+
+type ContextualAskJobEventListener = (event: AskJobEvent) => void;
+interface ContextualAskManager {
+    cancel(jobId: string): AskJobSnapshot;
+    capability(signal: AbortSignal): Promise<ContextualAskCapability>;
+    close(): Promise<void>;
+    create(request: AskJobCreateRequest): Promise<AskJobSnapshot>;
+    events(jobId: string, afterSequence?: number): readonly AskJobEvent[];
+    result(jobId: string): Promise<AskJobResultResponse>;
+    snapshot(jobId: string): AskJobSnapshot;
+    subscribe(jobId: string, listener: ContextualAskJobEventListener): () => void;
+}
+interface ContextualAskManagerDependencies {
+    readonly captureSnapshot: typeof captureAskReadSnapshot;
+    readonly createId: () => string;
+    readonly now: () => Date;
+}
+interface CreateContextualAskManagerOptions {
+    readonly coordinator: WorkspaceActivityCoordinator;
+    readonly enabled: boolean;
+    readonly executors?: readonly ContextualAskExecutor[];
+    readonly registry: SourceRegistry;
+    readonly root: string;
+    readonly dependencies?: Partial<ContextualAskManagerDependencies>;
+}
+declare function createContextualAskManager(options: CreateContextualAskManagerOptions): ContextualAskManager;
+
+declare class ContextualAskError extends Error {
+    readonly code: ContextualAskErrorCode;
+    constructor(code: ContextualAskErrorCode, options?: Readonly<{
+        cause?: unknown;
+    }>);
+}
+
+interface CreateConfiguredKeyAskExecutorsOptions {
+    readonly ai: ResolvedAiOptions;
+    readonly environment: Readonly<Record<string, string | undefined>>;
+    readonly fetch?: typeof globalThis.fetch;
+    readonly defaultExecutor?: ContextualAskExecutorPreference;
+}
+/** Builds one isolated read-only Ask executor per configured Provider/model pair. */
+declare function createConfiguredKeyAskExecutors(options: CreateConfiguredKeyAskExecutorsOptions): readonly ContextualAskExecutor[];
+
+interface ComposeContextualAskExecutorsOptions {
+    readonly configuredKey: readonly ContextualAskExecutor[];
+    readonly managedCodex: ContextualAskExecutor;
+    readonly defaultExecutor?: ContextualAskExecutorPreference;
+}
+/** Orders independent executor implementations without coupling dev-server to Codex. */
+declare function composeContextualAskExecutors(options: ComposeContextualAskExecutorsOptions): readonly ContextualAskExecutor[];
+
 interface SpotPatchSession {
     readonly id: string;
     readonly token: string;
@@ -264,6 +355,7 @@ interface SpotPatchServerLogger {
 }
 interface CreateMiddlewareOptions {
     readonly agentManager?: AgentJobManager;
+    readonly contextualAskManager?: ContextualAskManager;
     readonly bootstrap?: RuntimeBootstrapOptions;
     readonly editorLauncher?: EditorLauncher;
     readonly externalAgentControl?: ExternalAgentControlPort;
@@ -280,6 +372,18 @@ declare function readJsonRequestBody(request: IncomingMessage, maximumBytes?: nu
 
 declare function isLoopbackHostname(hostname: string): boolean;
 
+type ContextualAskRoute = Readonly<{
+    kind: "capability";
+}> | Readonly<{
+    kind: "create";
+}> | Readonly<{
+    kind: "job";
+    action: "events" | "result" | "cancel";
+    jobId: string;
+}>;
+declare function matchContextualAskPath(pathname: string): ContextualAskRoute | undefined;
+declare function handleContextualAskRequest(request: IncomingMessage, response: ServerResponse, route: ContextualAskRoute, manager: ContextualAskManager | undefined, logger?: SpotPatchServerLogger): Promise<void>;
+
 interface SourceRegistrationServiceOptions {
     readonly internalSecret: string;
     readonly options: ResolvedSpotPatchOptions;
@@ -310,6 +414,7 @@ interface SerializedSpotPatchOptions {
     readonly budget: Readonly<ContextBudget>;
     readonly debug: boolean;
     readonly dataFlow: false | SpotPatchDataFlowOptions;
+    readonly contextualAsk: ContextualAskOptions;
     readonly editor: SpotPatchEditorPreference;
     readonly enabled: boolean;
     readonly externalAgent: boolean;
@@ -323,4 +428,4 @@ interface SerializedSpotPatchOptions {
 declare function serializeResolvedSpotPatchOptions(options: ResolvedSpotPatchOptions): SerializedSpotPatchOptions;
 declare function parseSerializedSpotPatchOptions(value: unknown): ResolvedSpotPatchOptions;
 
-export { type AgentJobEventListener, type AgentJobManager, type CreateAgentJobManagerOptions, type CreateExternalHandoffServiceOptions, type CreateMiddlewareOptions, DEFAULT_EXCLUDE, DEFAULT_OPTIONS, type DiscoverProjectValidationCheckOptions, type EnvironmentAiConfiguration, type ExternalAgentControlPort, type ExternalHandoffService, type FilterEntry, type IntegrationFileChange, type IntegrationPlan, type ResolveManagedExecutionValidationOptions, type ResolveProjectOptionsInput, type ResolveProjectValidationChecksOptions, type ResolvedManagedExecutionValidation, type ResolvedRuntimeBootstrapOptions, type ResolvedSpotPatchDataFlowOptions, type ResolvedSpotPatchOptions, type RuntimeBootstrapOptions, type SerializedFilterEntry, type SerializedSpotPatchOptions, type SimpleAiOptions, type SourceRegistrationHandler, type SourceRegistrationService, type SourceRegistrationServiceOptions, type SourceRegistry, type SpotPatchAiOptions, type SpotPatchDataFlowOptions, type SpotPatchMiddleware, type SpotPatchNext, type SpotPatchOptions, type SpotPatchServerLogger, type SpotPatchSession, applyIntegrationPlan, createAgentJobManager, createExternalHandoffService, createIntegrationFileChange, createRuntimeAiConfig, createRuntimeDataFlowConfig, createSession, createSourceRegistrationService, createSourceRegistry, createSpotPatchMiddleware, discoverProjectValidationCheck, integrationPathExists, isLoopbackHostname, parseSerializedSpotPatchOptions, readIntegrationFile, readJsonRequestBody, readRuntimeBootstrap, resolveCredentialEnvironment, resolveEnvironmentAiConfiguration, resolveManagedExecutionValidation, resolveOptions, resolveProjectOptions, resolveProjectValidationChecks, resolveRuntimeBootstrapOptions, serializeResolvedSpotPatchOptions };
+export { type AgentJobEventListener, type AgentJobManager, type CaptureAskReadSnapshotOptions, type CapturedAskReadSnapshot, type ComposeContextualAskExecutorsOptions, ContextualAskError, type ContextualAskJobEventListener, type ContextualAskManager, type ContextualAskRoute, type CreateAgentJobManagerOptions, type CreateConfiguredKeyAskExecutorsOptions, type CreateContextualAskManagerOptions, type CreateExternalHandoffServiceOptions, type CreateMiddlewareOptions, DEFAULT_EXCLUDE, DEFAULT_OPTIONS, type DiscoverProjectValidationCheckOptions, type EnvironmentAiConfiguration, type ExternalAgentControlPort, type ExternalHandoffService, type FilterEntry, type IntegrationFileChange, type IntegrationPlan, type ResolveManagedExecutionValidationOptions, type ResolveProjectOptionsInput, type ResolveProjectValidationChecksOptions, type ResolvedContextualAskOptions, type ResolvedManagedExecutionValidation, type ResolvedRuntimeBootstrapOptions, type ResolvedSpotPatchDataFlowOptions, type ResolvedSpotPatchOptions, type RuntimeBootstrapOptions, type SerializedFilterEntry, type SerializedSpotPatchOptions, type SimpleAiOptions, type SourceRegistrationHandler, type SourceRegistrationService, type SourceRegistrationServiceOptions, type SourceRegistry, type SpotPatchAiOptions, type SpotPatchDataFlowOptions, type SpotPatchMiddleware, type SpotPatchNext, type SpotPatchOptions, type SpotPatchServerLogger, type SpotPatchSession, type WorkspaceActivityCoordinator, type WorkspaceActivityKind, type WorkspaceActivityLease, applyIntegrationPlan, captureAskReadSnapshot, composeContextualAskExecutors, createAgentJobManager, createConfiguredKeyAskExecutors, createContextualAskManager, createExternalHandoffService, createIntegrationFileChange, createRuntimeAiConfig, createRuntimeDataFlowConfig, createSession, createSourceRegistrationService, createSourceRegistry, createSpotPatchMiddleware, createWorkspaceActivityCoordinator, discoverProjectValidationCheck, handleContextualAskRequest, integrationPathExists, isLoopbackHostname, matchContextualAskPath, parseSerializedSpotPatchOptions, readIntegrationFile, readJsonRequestBody, readRuntimeBootstrap, resolveCredentialEnvironment, resolveEnvironmentAiConfiguration, resolveManagedExecutionValidation, resolveOptions, resolveProjectOptions, resolveProjectValidationChecks, resolveRuntimeBootstrapOptions, serializeResolvedSpotPatchOptions };

package/dist/index.d.ts

@@ -1,8 +1,18 @@
-import { applyPreparedAgentChange, executeAgentChange, inspectAgentWorkspace, probeProviderCapability, resolveProviderCredential, revertPreparedAgentChange } from '@spotpatch/agent';
-import { AgentJobEvent, AgentJobSnapshot, AgentJobCreateRequest, AgentCapabilityRequest, AgentCapabilitySnapshot, AgentJobResultResponse, AgentWorkspaceHealthSnapshot, ResolvedAiOptions, ExternalHandoffFramework, ExternalHandoffCapability, ExternalHandoffPublishRequest, SpotAnnotation, ExternalHandoffPublishResult, ExternalHandoffStatusResult, ExternalAgentControlStatus, ExternalAgentControlConnectRequest, ExternalAgentControlDisconnectRequest, ExternalAgentControlCancelRequest, ExternalAgentManagedResult, SpotPatchEditorPreference, ContextBudget, SpotPatchLocalePreference, DataFlowLimits, AiProviderProtocol, AiProviderAuthentication, AiExecutionOptions, AiOptions, RuntimeAiConfig, RuntimeDataFlowConfig, ResolvedAgentCheckDefinition, AgentLimits, SpotPatchRuntimeConfig } from '@spotpatch/shared';
+import { applyPreparedAgentChange, executeAgentChange, inspectAgentWorkspace, probeProviderCapability, resolveProviderCredential, revertPreparedAgentChange, AskSourceGrant, ContextualAskReadSnapshot, AskSourceGrantEntry, ContextualAskExecutor } from '@spotpatch/agent';
+import { AgentJobEvent, AgentJobSnapshot, AgentJobCreateRequest, AgentCapabilityRequest, AgentCapabilitySnapshot, AgentJobResultResponse, AgentWorkspaceHealthSnapshot, ResolvedAiOptions, ExternalHandoffFramework, ExternalHandoffCapability, ExternalHandoffPublishRequest, SpotAnnotation, ExternalHandoffPublishResult, ExternalHandoffStatusResult, ExternalAgentControlStatus, ExternalAgentControlConnectRequest, ExternalAgentControlDisconnectRequest, ExternalAgentControlCancelRequest, ExternalAgentManagedResult, SpotPatchEditorPreference, ContextBudget, SpotPatchLocalePreference, DataFlowLimits, ContextualAskExecutorPreference, AiProviderProtocol, AiProviderAuthentication, AiExecutionOptions, AiOptions, ContextualAskOptions, RuntimeAiConfig, RuntimeDataFlowConfig, ResolvedAgentCheckDefinition, AgentLimits, SpotSelectionContext, AskJobEvent, AskJobSnapshot, ContextualAskCapability, AskJobCreateRequest, AskJobResultResponse, ContextualAskErrorCode, SpotPatchRuntimeConfig } from '@spotpatch/shared';
 import { SourceFilterEntry } from '@spotpatch/compiler';
 import { IncomingMessage, ServerResponse } from 'node:http';
 
+type WorkspaceActivityKind = "ask" | "change";
+interface WorkspaceActivityLease {
+    release(): void;
+}
+interface WorkspaceActivityCoordinator {
+    acquire(kind: WorkspaceActivityKind): WorkspaceActivityLease | undefined;
+    current(): WorkspaceActivityKind | undefined;
+}
+declare function createWorkspaceActivityCoordinator(): WorkspaceActivityCoordinator;
+
 type AgentJobEventListener = (event: AgentJobEvent) => void;
 interface AgentJobManager {
     apply(jobId: string): Promise<AgentJobSnapshot>;
@@ -32,6 +42,7 @@ interface CreateAgentJobManagerOptions {
     readonly environment?: Readonly<Record<string, string | undefined>>;
     readonly fetch?: typeof globalThis.fetch;
     readonly root: string;
+    readonly coordinator?: WorkspaceActivityCoordinator;
 }
 declare function createAgentJobManager(options: CreateAgentJobManagerOptions): AgentJobManager;
 
@@ -93,6 +104,11 @@ interface SpotPatchOptions {
     readonly ai?: SpotPatchAiOptions;
     readonly dataFlow?: false | SpotPatchDataFlowOptions;
     readonly externalAgent?: boolean;
+    readonly contextualAsk?: ContextualAskOptions;
+}
+interface ResolvedContextualAskOptions {
+    readonly enabled: boolean;
+    readonly defaultExecutor?: ContextualAskExecutorPreference;
 }
 interface ResolvedSpotPatchOptions {
     readonly enabled: boolean;
@@ -111,6 +127,7 @@ interface ResolvedSpotPatchOptions {
     readonly externalAgent: Readonly<{
         enabled: boolean;
     }>;
+    readonly contextualAsk: ResolvedContextualAskOptions;
 }
 interface ResolvedSpotPatchDataFlowOptions {
     readonly enabled: boolean;
@@ -155,11 +172,15 @@ declare const DEFAULT_OPTIONS: Readonly<{
             readonly graphMaxCallsites: 100;
             readonly analysisTimeoutMs: 2000;
             readonly reportMaxFields: 100;
+            readonly sourceMaxComponents: 256;
         }>;
     }>;
     externalAgent: Readonly<{
         enabled: false;
     }>;
+    contextualAsk: Readonly<{
+        enabled: false;
+    }>;
 }>;
 declare function createRuntimeAiConfig(options: false | ResolvedAiOptions): RuntimeAiConfig;
 declare function createRuntimeDataFlowConfig(options: ResolvedSpotPatchDataFlowOptions): RuntimeDataFlowConfig;
@@ -216,8 +237,9 @@ type SourceIdFactory = () => string;
 
 interface SourceRegistry {
     register(absolutePath: string): string;
-    registerDataFlowComponents(absolutePath: string, sourceVersion: string, components: readonly DataFlowComponentAnchorInput[]): void;
+    registerDataFlowComponents(absolutePath: string, sourceVersion: string, components: readonly DataFlowComponentAnchorInput[]): string;
     resolve(fileId: string): string | undefined;
+    findRegisteredId(absolutePath: string): string | undefined;
     resolveDataFlowComponent(componentSourceId: string): DataFlowComponentAnchor | undefined;
     clear(): void;
 }
@@ -235,6 +257,75 @@ interface SourceRegistryOptions {
 }
 declare function createSourceRegistry(options?: SourceRegistryOptions): SourceRegistry;
 
+interface CapturedAskReadSnapshot {
+    readonly grant: AskSourceGrant;
+    readonly snapshot: ContextualAskReadSnapshot;
+    dispose(): void;
+    isStale(): Promise<boolean>;
+    projectCitation(handleId: string, startLine: number, endLine: number): AskSourceGrantEntry & Readonly<{
+        startLine: number;
+        endLine: number;
+    }>;
+}
+interface CaptureAskReadSnapshotOptions {
+    readonly root: string;
+    readonly registry: SourceRegistry;
+    readonly selection: SpotSelectionContext;
+    readonly signal?: AbortSignal;
+    readonly createHandleId?: () => string;
+}
+declare function captureAskReadSnapshot(options: CaptureAskReadSnapshotOptions): Promise<CapturedAskReadSnapshot>;
+
+type ContextualAskJobEventListener = (event: AskJobEvent) => void;
+interface ContextualAskManager {
+    cancel(jobId: string): AskJobSnapshot;
+    capability(signal: AbortSignal): Promise<ContextualAskCapability>;
+    close(): Promise<void>;
+    create(request: AskJobCreateRequest): Promise<AskJobSnapshot>;
+    events(jobId: string, afterSequence?: number): readonly AskJobEvent[];
+    result(jobId: string): Promise<AskJobResultResponse>;
+    snapshot(jobId: string): AskJobSnapshot;
+    subscribe(jobId: string, listener: ContextualAskJobEventListener): () => void;
+}
+interface ContextualAskManagerDependencies {
+    readonly captureSnapshot: typeof captureAskReadSnapshot;
+    readonly createId: () => string;
+    readonly now: () => Date;
+}
+interface CreateContextualAskManagerOptions {
+    readonly coordinator: WorkspaceActivityCoordinator;
+    readonly enabled: boolean;
+    readonly executors?: readonly ContextualAskExecutor[];
+    readonly registry: SourceRegistry;
+    readonly root: string;
+    readonly dependencies?: Partial<ContextualAskManagerDependencies>;
+}
+declare function createContextualAskManager(options: CreateContextualAskManagerOptions): ContextualAskManager;
+
+declare class ContextualAskError extends Error {
+    readonly code: ContextualAskErrorCode;
+    constructor(code: ContextualAskErrorCode, options?: Readonly<{
+        cause?: unknown;
+    }>);
+}
+
+interface CreateConfiguredKeyAskExecutorsOptions {
+    readonly ai: ResolvedAiOptions;
+    readonly environment: Readonly<Record<string, string | undefined>>;
+    readonly fetch?: typeof globalThis.fetch;
+    readonly defaultExecutor?: ContextualAskExecutorPreference;
+}
+/** Builds one isolated read-only Ask executor per configured Provider/model pair. */
+declare function createConfiguredKeyAskExecutors(options: CreateConfiguredKeyAskExecutorsOptions): readonly ContextualAskExecutor[];
+
+interface ComposeContextualAskExecutorsOptions {
+    readonly configuredKey: readonly ContextualAskExecutor[];
+    readonly managedCodex: ContextualAskExecutor;
+    readonly defaultExecutor?: ContextualAskExecutorPreference;
+}
+/** Orders independent executor implementations without coupling dev-server to Codex. */
+declare function composeContextualAskExecutors(options: ComposeContextualAskExecutorsOptions): readonly ContextualAskExecutor[];
+
 interface SpotPatchSession {
     readonly id: string;
     readonly token: string;
@@ -264,6 +355,7 @@ interface SpotPatchServerLogger {
 }
 interface CreateMiddlewareOptions {
     readonly agentManager?: AgentJobManager;
+    readonly contextualAskManager?: ContextualAskManager;
     readonly bootstrap?: RuntimeBootstrapOptions;
     readonly editorLauncher?: EditorLauncher;
     readonly externalAgentControl?: ExternalAgentControlPort;
@@ -280,6 +372,18 @@ declare function readJsonRequestBody(request: IncomingMessage, maximumBytes?: nu
 
 declare function isLoopbackHostname(hostname: string): boolean;
 
+type ContextualAskRoute = Readonly<{
+    kind: "capability";
+}> | Readonly<{
+    kind: "create";
+}> | Readonly<{
+    kind: "job";
+    action: "events" | "result" | "cancel";
+    jobId: string;
+}>;
+declare function matchContextualAskPath(pathname: string): ContextualAskRoute | undefined;
+declare function handleContextualAskRequest(request: IncomingMessage, response: ServerResponse, route: ContextualAskRoute, manager: ContextualAskManager | undefined, logger?: SpotPatchServerLogger): Promise<void>;
+
 interface SourceRegistrationServiceOptions {
     readonly internalSecret: string;
     readonly options: ResolvedSpotPatchOptions;
@@ -310,6 +414,7 @@ interface SerializedSpotPatchOptions {
     readonly budget: Readonly<ContextBudget>;
     readonly debug: boolean;
     readonly dataFlow: false | SpotPatchDataFlowOptions;
+    readonly contextualAsk: ContextualAskOptions;
     readonly editor: SpotPatchEditorPreference;
     readonly enabled: boolean;
     readonly externalAgent: boolean;
@@ -323,4 +428,4 @@ interface SerializedSpotPatchOptions {
 declare function serializeResolvedSpotPatchOptions(options: ResolvedSpotPatchOptions): SerializedSpotPatchOptions;
 declare function parseSerializedSpotPatchOptions(value: unknown): ResolvedSpotPatchOptions;
 
-export { type AgentJobEventListener, type AgentJobManager, type CreateAgentJobManagerOptions, type CreateExternalHandoffServiceOptions, type CreateMiddlewareOptions, DEFAULT_EXCLUDE, DEFAULT_OPTIONS, type DiscoverProjectValidationCheckOptions, type EnvironmentAiConfiguration, type ExternalAgentControlPort, type ExternalHandoffService, type FilterEntry, type IntegrationFileChange, type IntegrationPlan, type ResolveManagedExecutionValidationOptions, type ResolveProjectOptionsInput, type ResolveProjectValidationChecksOptions, type ResolvedManagedExecutionValidation, type ResolvedRuntimeBootstrapOptions, type ResolvedSpotPatchDataFlowOptions, type ResolvedSpotPatchOptions, type RuntimeBootstrapOptions, type SerializedFilterEntry, type SerializedSpotPatchOptions, type SimpleAiOptions, type SourceRegistrationHandler, type SourceRegistrationService, type SourceRegistrationServiceOptions, type SourceRegistry, type SpotPatchAiOptions, type SpotPatchDataFlowOptions, type SpotPatchMiddleware, type SpotPatchNext, type SpotPatchOptions, type SpotPatchServerLogger, type SpotPatchSession, applyIntegrationPlan, createAgentJobManager, createExternalHandoffService, createIntegrationFileChange, createRuntimeAiConfig, createRuntimeDataFlowConfig, createSession, createSourceRegistrationService, createSourceRegistry, createSpotPatchMiddleware, discoverProjectValidationCheck, integrationPathExists, isLoopbackHostname, parseSerializedSpotPatchOptions, readIntegrationFile, readJsonRequestBody, readRuntimeBootstrap, resolveCredentialEnvironment, resolveEnvironmentAiConfiguration, resolveManagedExecutionValidation, resolveOptions, resolveProjectOptions, resolveProjectValidationChecks, resolveRuntimeBootstrapOptions, serializeResolvedSpotPatchOptions };
+export { type AgentJobEventListener, type AgentJobManager, type CaptureAskReadSnapshotOptions, type CapturedAskReadSnapshot, type ComposeContextualAskExecutorsOptions, ContextualAskError, type ContextualAskJobEventListener, type ContextualAskManager, type ContextualAskRoute, type CreateAgentJobManagerOptions, type CreateConfiguredKeyAskExecutorsOptions, type CreateContextualAskManagerOptions, type CreateExternalHandoffServiceOptions, type CreateMiddlewareOptions, DEFAULT_EXCLUDE, DEFAULT_OPTIONS, type DiscoverProjectValidationCheckOptions, type EnvironmentAiConfiguration, type ExternalAgentControlPort, type ExternalHandoffService, type FilterEntry, type IntegrationFileChange, type IntegrationPlan, type ResolveManagedExecutionValidationOptions, type ResolveProjectOptionsInput, type ResolveProjectValidationChecksOptions, type ResolvedContextualAskOptions, type ResolvedManagedExecutionValidation, type ResolvedRuntimeBootstrapOptions, type ResolvedSpotPatchDataFlowOptions, type ResolvedSpotPatchOptions, type RuntimeBootstrapOptions, type SerializedFilterEntry, type SerializedSpotPatchOptions, type SimpleAiOptions, type SourceRegistrationHandler, type SourceRegistrationService, type SourceRegistrationServiceOptions, type SourceRegistry, type SpotPatchAiOptions, type SpotPatchDataFlowOptions, type SpotPatchMiddleware, type SpotPatchNext, type SpotPatchOptions, type SpotPatchServerLogger, type SpotPatchSession, type WorkspaceActivityCoordinator, type WorkspaceActivityKind, type WorkspaceActivityLease, applyIntegrationPlan, captureAskReadSnapshot, composeContextualAskExecutors, createAgentJobManager, createConfiguredKeyAskExecutors, createContextualAskManager, createExternalHandoffService, createIntegrationFileChange, createRuntimeAiConfig, createRuntimeDataFlowConfig, createSession, createSourceRegistrationService, createSourceRegistry, createSpotPatchMiddleware, createWorkspaceActivityCoordinator, discoverProjectValidationCheck, handleContextualAskRequest, integrationPathExists, isLoopbackHostname, matchContextualAskPath, parseSerializedSpotPatchOptions, readIntegrationFile, readJsonRequestBody, readRuntimeBootstrap, resolveCredentialEnvironment, resolveEnvironmentAiConfiguration, resolveManagedExecutionValidation, resolveOptions, resolveProjectOptions, resolveProjectValidationChecks, resolveRuntimeBootstrapOptions, serializeResolvedSpotPatchOptions };