@agentcash/discovery 0.1.0 → 0.1.2

package/dist/index.d.cts

@@ -94,13 +94,199 @@ interface DiscoverDetailedOptions extends DiscoverOptions {
     includeInteropMpp?: boolean;
 }
 
+type McpFailureCause = 'not_found' | 'network' | 'timeout' | 'parse';
+type McpAuthMode = 'paid' | 'siwx' | 'apiKey' | 'unprotected';
+interface McpOpenApiInfo {
+    title: string;
+    version?: string;
+    description?: string;
+}
+interface McpEndpointSummary {
+    path: string;
+    method: HttpMethod;
+    summary: string;
+    price?: string;
+    protocols?: string[];
+    authMode?: McpAuthMode;
+}
+interface McpGuidance {
+    guidanceAvailable: boolean;
+    guidanceTokens?: number;
+    guidance?: string;
+}
+interface DiscoverForMcpOptions {
+    target: string;
+    includeGuidance?: boolean;
+    guidanceAutoIncludeMaxTokens?: number;
+    compatMode?: CompatibilityMode;
+    fetcher?: DiscoveryFetcher;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}
+interface DiscoverForMcpSuccess extends McpGuidance {
+    found: true;
+    origin: string;
+    source: string;
+    info?: McpOpenApiInfo;
+    endpoints: McpEndpointSummary[];
+    warnings: DiscoveryWarning[];
+}
+interface DiscoverForMcpFailure {
+    found: false;
+    origin: string;
+    cause: McpFailureCause;
+    message?: string;
+    warnings: DiscoveryWarning[];
+}
+type DiscoverForMcpResult = DiscoverForMcpSuccess | DiscoverForMcpFailure;
+interface EndpointMethodAdvisory {
+    method: HttpMethod;
+    summary?: string;
+    estimatedPrice?: string;
+    protocols?: string[];
+    authMode?: McpAuthMode;
+    inputSchema?: Record<string, unknown>;
+    operationSchema?: Record<string, unknown>;
+}
+interface InspectEndpointForMcpOptions {
+    target: string;
+    endpointUrl: string;
+    compatMode?: CompatibilityMode;
+    fetcher?: DiscoveryFetcher;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}
+interface InspectEndpointForMcpSuccess {
+    found: true;
+    origin: string;
+    path: string;
+    specMethods: HttpMethod[];
+    advisories: Partial<Record<HttpMethod, EndpointMethodAdvisory>>;
+    warnings: DiscoveryWarning[];
+}
+interface InspectEndpointForMcpFailure {
+    found: false;
+    origin: string;
+    path: string;
+    cause: McpFailureCause;
+    message?: string;
+    warnings: DiscoveryWarning[];
+}
+type InspectEndpointForMcpResult = InspectEndpointForMcpSuccess | InspectEndpointForMcpFailure;
+declare function discoverForMcp(options: DiscoverForMcpOptions): Promise<DiscoverForMcpResult>;
+declare function inspectEndpointForMcp(options: InspectEndpointForMcpOptions): Promise<InspectEndpointForMcpResult>;
+
 declare const UPGRADE_WARNING_CODES: readonly ["LEGACY_WELL_KNOWN_USED", "LEGACY_DNS_USED", "LEGACY_DNS_PLAIN_URL", "LEGACY_INSTRUCTIONS_USED", "LEGACY_OWNERSHIP_PROOFS_USED", "OPENAPI_AUTH_MODE_MISSING", "OPENAPI_TOP_LEVEL_INVALID"];
 declare function computeUpgradeSignal(warnings: DiscoveryWarning[]): {
     upgradeSuggested: boolean;
     upgradeReasons: string[];
 };
 
+type HarnessClientId = 'claude-code' | 'skill-cli' | 'generic-mcp' | 'generic';
+interface HarnessClientProfile {
+    id: HarnessClientId;
+    label: string;
+    surface: 'mcp' | 'skill-cli' | 'generic';
+    defaultContextWindowTokens: number;
+    zeroHopBudgetPercent: number;
+    notes: string;
+}
+interface ContextHarnessL0 {
+    layer: 'L0';
+    intentTriggers: string[];
+    installCommand: string;
+    deliverySurfaces: string[];
+    summary: string;
+    estimatedTokens: number;
+}
+interface ContextHarnessL1 {
+    layer: 'L1';
+    domain: string;
+    domainClass: 'first-party' | 'ugc';
+    selectedDiscoveryStage: DiscoverResult['selectedStage'] | null;
+    summary: string;
+    fanoutCommands: string[];
+    estimatedTokens: number;
+}
+interface ContextHarnessL2Entry {
+    resourceKey: string;
+    method: DiscoveryResource['method'];
+    path: string;
+    source: DiscoveryResource['source'];
+    authMode: DiscoveryResource['authHint'] | null;
+}
+interface ContextHarnessL2 {
+    layer: 'L2';
+    command: string;
+    tokenLight: boolean;
+    resourceCount: number;
+    resources: ContextHarnessL2Entry[];
+}
+interface ContextHarnessL3 {
+    layer: 'L3';
+    command: string;
+    detailLevel: 'endpoint-schema-and-metadata';
+    countsByAuthMode: Record<'paid' | 'siwx' | 'apiKey' | 'unprotected' | 'unknown', number>;
+    countsBySource: Record<string, number>;
+    pricedResourceCount: number;
+}
+interface ContextHarnessL4 {
+    layer: 'L4';
+    guidanceSource: 'llms.txt' | 'none';
+    llmsTxtUrl: string | null;
+    llmsTxtTokenEstimate: number;
+    guidancePreview: string | null;
+    guidanceStatus: 'present' | 'advertised_but_unfetched' | 'missing' | 'not_advertised';
+}
+interface ContextHarnessL5 {
+    layer: 'L5';
+    status: 'out_of_scope';
+    note: string;
+}
+interface ContextHarnessBudget {
+    contextWindowTokens: number;
+    zeroHopBudgetTokens: number;
+    estimatedZeroHopTokens: number;
+    withinBudget: boolean;
+}
+interface ContextHarnessReport {
+    target: string;
+    origin: string;
+    client: HarnessClientProfile;
+    budget: ContextHarnessBudget;
+    levels: {
+        l0: ContextHarnessL0;
+        l1: ContextHarnessL1;
+        l2: ContextHarnessL2;
+        l3: ContextHarnessL3;
+        l4: ContextHarnessL4;
+        l5: ContextHarnessL5;
+    };
+    diagnostics: {
+        warningCount: number;
+        errorWarningCount: number;
+        selectedStage: DiscoverResult['selectedStage'] | null;
+        upgradeSuggested: boolean;
+        upgradeReasons: string[];
+    };
+}
+interface BuildContextHarnessReportOptions {
+    target: string;
+    result: DiscoverDetailedResult;
+    client?: HarnessClientId;
+    contextWindowTokens?: number;
+}
+interface AuditContextHarnessOptions extends Omit<DiscoverDetailedOptions, 'rawView'> {
+    client?: HarnessClientId;
+    contextWindowTokens?: number;
+}
+declare function getHarnessClientProfile(client?: HarnessClientId): HarnessClientProfile;
+declare function listHarnessClientProfiles(): HarnessClientProfile[];
+declare function buildContextHarnessReport(options: BuildContextHarnessReportOptions): ContextHarnessReport;
+declare function auditContextHarness(options: AuditContextHarnessOptions): Promise<ContextHarnessReport>;
+declare function defaultHarnessProbeCandidates(report: ContextHarnessReport): ProbeCandidate[];
+
 declare function discover(options: DiscoverOptions): Promise<DiscoverResult>;
 declare function discoverDetailed(options: DiscoverDetailedOptions): Promise<DiscoverDetailedResult>;
 
-export { type AuthMode, CompatibilityMode, type DiscoverDetailedOptions, type DiscoverDetailedResult, type DiscoverOptions, type DiscoverResult, type DiscoveryFetcher, type DiscoveryResource, type DiscoveryStage, type DiscoveryWarning, type HttpMethod, type PricingMode, type ProbeCandidate, type RawSources, type StageTrace, type TrustTier, type TxtResolver, UPGRADE_WARNING_CODES, type WarningSeverity, computeUpgradeSignal, discover, discoverDetailed };
+export { type AuthMode, CompatibilityMode, type ContextHarnessL0, type ContextHarnessL1, type ContextHarnessL2, type ContextHarnessL2Entry, type ContextHarnessL3, type ContextHarnessL4, type ContextHarnessL5, type ContextHarnessReport, type DiscoverDetailedOptions, type DiscoverDetailedResult, type DiscoverForMcpFailure, type DiscoverForMcpOptions, type DiscoverForMcpResult, type DiscoverForMcpSuccess, type DiscoverOptions, type DiscoverResult, type DiscoveryFetcher, type DiscoveryResource, type DiscoveryStage, type DiscoveryWarning, type EndpointMethodAdvisory, type HarnessClientId, type HarnessClientProfile, type HttpMethod, type InspectEndpointForMcpFailure, type InspectEndpointForMcpOptions, type InspectEndpointForMcpResult, type InspectEndpointForMcpSuccess, type PricingMode, type ProbeCandidate, type RawSources, type StageTrace, type TrustTier, type TxtResolver, UPGRADE_WARNING_CODES, type WarningSeverity, auditContextHarness, buildContextHarnessReport, computeUpgradeSignal, defaultHarnessProbeCandidates, discover, discoverDetailed, discoverForMcp, getHarnessClientProfile, inspectEndpointForMcp, listHarnessClientProfiles };

package/dist/index.d.ts

@@ -94,13 +94,199 @@ interface DiscoverDetailedOptions extends DiscoverOptions {
     includeInteropMpp?: boolean;
 }
 
+type McpFailureCause = 'not_found' | 'network' | 'timeout' | 'parse';
+type McpAuthMode = 'paid' | 'siwx' | 'apiKey' | 'unprotected';
+interface McpOpenApiInfo {
+    title: string;
+    version?: string;
+    description?: string;
+}
+interface McpEndpointSummary {
+    path: string;
+    method: HttpMethod;
+    summary: string;
+    price?: string;
+    protocols?: string[];
+    authMode?: McpAuthMode;
+}
+interface McpGuidance {
+    guidanceAvailable: boolean;
+    guidanceTokens?: number;
+    guidance?: string;
+}
+interface DiscoverForMcpOptions {
+    target: string;
+    includeGuidance?: boolean;
+    guidanceAutoIncludeMaxTokens?: number;
+    compatMode?: CompatibilityMode;
+    fetcher?: DiscoveryFetcher;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}
+interface DiscoverForMcpSuccess extends McpGuidance {
+    found: true;
+    origin: string;
+    source: string;
+    info?: McpOpenApiInfo;
+    endpoints: McpEndpointSummary[];
+    warnings: DiscoveryWarning[];
+}
+interface DiscoverForMcpFailure {
+    found: false;
+    origin: string;
+    cause: McpFailureCause;
+    message?: string;
+    warnings: DiscoveryWarning[];
+}
+type DiscoverForMcpResult = DiscoverForMcpSuccess | DiscoverForMcpFailure;
+interface EndpointMethodAdvisory {
+    method: HttpMethod;
+    summary?: string;
+    estimatedPrice?: string;
+    protocols?: string[];
+    authMode?: McpAuthMode;
+    inputSchema?: Record<string, unknown>;
+    operationSchema?: Record<string, unknown>;
+}
+interface InspectEndpointForMcpOptions {
+    target: string;
+    endpointUrl: string;
+    compatMode?: CompatibilityMode;
+    fetcher?: DiscoveryFetcher;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}
+interface InspectEndpointForMcpSuccess {
+    found: true;
+    origin: string;
+    path: string;
+    specMethods: HttpMethod[];
+    advisories: Partial<Record<HttpMethod, EndpointMethodAdvisory>>;
+    warnings: DiscoveryWarning[];
+}
+interface InspectEndpointForMcpFailure {
+    found: false;
+    origin: string;
+    path: string;
+    cause: McpFailureCause;
+    message?: string;
+    warnings: DiscoveryWarning[];
+}
+type InspectEndpointForMcpResult = InspectEndpointForMcpSuccess | InspectEndpointForMcpFailure;
+declare function discoverForMcp(options: DiscoverForMcpOptions): Promise<DiscoverForMcpResult>;
+declare function inspectEndpointForMcp(options: InspectEndpointForMcpOptions): Promise<InspectEndpointForMcpResult>;
+
 declare const UPGRADE_WARNING_CODES: readonly ["LEGACY_WELL_KNOWN_USED", "LEGACY_DNS_USED", "LEGACY_DNS_PLAIN_URL", "LEGACY_INSTRUCTIONS_USED", "LEGACY_OWNERSHIP_PROOFS_USED", "OPENAPI_AUTH_MODE_MISSING", "OPENAPI_TOP_LEVEL_INVALID"];
 declare function computeUpgradeSignal(warnings: DiscoveryWarning[]): {
     upgradeSuggested: boolean;
     upgradeReasons: string[];
 };
 
+type HarnessClientId = 'claude-code' | 'skill-cli' | 'generic-mcp' | 'generic';
+interface HarnessClientProfile {
+    id: HarnessClientId;
+    label: string;
+    surface: 'mcp' | 'skill-cli' | 'generic';
+    defaultContextWindowTokens: number;
+    zeroHopBudgetPercent: number;
+    notes: string;
+}
+interface ContextHarnessL0 {
+    layer: 'L0';
+    intentTriggers: string[];
+    installCommand: string;
+    deliverySurfaces: string[];
+    summary: string;
+    estimatedTokens: number;
+}
+interface ContextHarnessL1 {
+    layer: 'L1';
+    domain: string;
+    domainClass: 'first-party' | 'ugc';
+    selectedDiscoveryStage: DiscoverResult['selectedStage'] | null;
+    summary: string;
+    fanoutCommands: string[];
+    estimatedTokens: number;
+}
+interface ContextHarnessL2Entry {
+    resourceKey: string;
+    method: DiscoveryResource['method'];
+    path: string;
+    source: DiscoveryResource['source'];
+    authMode: DiscoveryResource['authHint'] | null;
+}
+interface ContextHarnessL2 {
+    layer: 'L2';
+    command: string;
+    tokenLight: boolean;
+    resourceCount: number;
+    resources: ContextHarnessL2Entry[];
+}
+interface ContextHarnessL3 {
+    layer: 'L3';
+    command: string;
+    detailLevel: 'endpoint-schema-and-metadata';
+    countsByAuthMode: Record<'paid' | 'siwx' | 'apiKey' | 'unprotected' | 'unknown', number>;
+    countsBySource: Record<string, number>;
+    pricedResourceCount: number;
+}
+interface ContextHarnessL4 {
+    layer: 'L4';
+    guidanceSource: 'llms.txt' | 'none';
+    llmsTxtUrl: string | null;
+    llmsTxtTokenEstimate: number;
+    guidancePreview: string | null;
+    guidanceStatus: 'present' | 'advertised_but_unfetched' | 'missing' | 'not_advertised';
+}
+interface ContextHarnessL5 {
+    layer: 'L5';
+    status: 'out_of_scope';
+    note: string;
+}
+interface ContextHarnessBudget {
+    contextWindowTokens: number;
+    zeroHopBudgetTokens: number;
+    estimatedZeroHopTokens: number;
+    withinBudget: boolean;
+}
+interface ContextHarnessReport {
+    target: string;
+    origin: string;
+    client: HarnessClientProfile;
+    budget: ContextHarnessBudget;
+    levels: {
+        l0: ContextHarnessL0;
+        l1: ContextHarnessL1;
+        l2: ContextHarnessL2;
+        l3: ContextHarnessL3;
+        l4: ContextHarnessL4;
+        l5: ContextHarnessL5;
+    };
+    diagnostics: {
+        warningCount: number;
+        errorWarningCount: number;
+        selectedStage: DiscoverResult['selectedStage'] | null;
+        upgradeSuggested: boolean;
+        upgradeReasons: string[];
+    };
+}
+interface BuildContextHarnessReportOptions {
+    target: string;
+    result: DiscoverDetailedResult;
+    client?: HarnessClientId;
+    contextWindowTokens?: number;
+}
+interface AuditContextHarnessOptions extends Omit<DiscoverDetailedOptions, 'rawView'> {
+    client?: HarnessClientId;
+    contextWindowTokens?: number;
+}
+declare function getHarnessClientProfile(client?: HarnessClientId): HarnessClientProfile;
+declare function listHarnessClientProfiles(): HarnessClientProfile[];
+declare function buildContextHarnessReport(options: BuildContextHarnessReportOptions): ContextHarnessReport;
+declare function auditContextHarness(options: AuditContextHarnessOptions): Promise<ContextHarnessReport>;
+declare function defaultHarnessProbeCandidates(report: ContextHarnessReport): ProbeCandidate[];
+
 declare function discover(options: DiscoverOptions): Promise<DiscoverResult>;
 declare function discoverDetailed(options: DiscoverDetailedOptions): Promise<DiscoverDetailedResult>;
 
-export { type AuthMode, CompatibilityMode, type DiscoverDetailedOptions, type DiscoverDetailedResult, type DiscoverOptions, type DiscoverResult, type DiscoveryFetcher, type DiscoveryResource, type DiscoveryStage, type DiscoveryWarning, type HttpMethod, type PricingMode, type ProbeCandidate, type RawSources, type StageTrace, type TrustTier, type TxtResolver, UPGRADE_WARNING_CODES, type WarningSeverity, computeUpgradeSignal, discover, discoverDetailed };
+export { type AuthMode, CompatibilityMode, type ContextHarnessL0, type ContextHarnessL1, type ContextHarnessL2, type ContextHarnessL2Entry, type ContextHarnessL3, type ContextHarnessL4, type ContextHarnessL5, type ContextHarnessReport, type DiscoverDetailedOptions, type DiscoverDetailedResult, type DiscoverForMcpFailure, type DiscoverForMcpOptions, type DiscoverForMcpResult, type DiscoverForMcpSuccess, type DiscoverOptions, type DiscoverResult, type DiscoveryFetcher, type DiscoveryResource, type DiscoveryStage, type DiscoveryWarning, type EndpointMethodAdvisory, type HarnessClientId, type HarnessClientProfile, type HttpMethod, type InspectEndpointForMcpFailure, type InspectEndpointForMcpOptions, type InspectEndpointForMcpResult, type InspectEndpointForMcpSuccess, type PricingMode, type ProbeCandidate, type RawSources, type StageTrace, type TrustTier, type TxtResolver, UPGRADE_WARNING_CODES, type WarningSeverity, auditContextHarness, buildContextHarnessReport, computeUpgradeSignal, defaultHarnessProbeCandidates, discover, discoverDetailed, discoverForMcp, getHarnessClientProfile, inspectEndpointForMcp, listHarnessClientProfiles };